-
Notifications
You must be signed in to change notification settings - Fork 58
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated documentation and plantuml diagrams + improved PDS exec #1213
- PDS web and infra scan product executors do now use the NetworkTargetProductServerDataAdapterConfigurationStrategy as well, so user, password and identifier parts are automatically handled. - updated network target documentation
- Loading branch information
Showing
7 changed files
with
199 additions
and
87 deletions.
There are no files selected for viewing
211 changes: 158 additions & 53 deletions
211
sechub-doc/src/docs/asciidoc/diagrams/diagram_target_architecture.plantuml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,62 +1,167 @@ | ||
| ' SPDX-License-Identifier: MIT | ||
| @startuml | ||
| hide fields | ||
| 'skinparam linetype polyline | ||
| skinparam linetype ortho | ||
| interface ProductExecutor{ | ||
| + List<ProductResult> execute() | ||
| + ScanType getScanType() | ||
| + int getVersion() | ||
| + boolean isMultipleConfigurationAllomwed() | ||
| } | ||
| class SerecoReportProductExecutor implements ProductExecutor | ||
|
|
||
| class ProductExecutorData{ | ||
| List<NetworkTargetInfo> networkTargetInfoList; | ||
| NetworkTargetProductServerDataProvider NetworkTargetProductServerDataProvider; | ||
|
|
||
| ProductExecutorContext productExecutorContext; | ||
| SecHubExecutionContext sechubExecutionContext; | ||
| UUIDTraceLogID traceLogId; | ||
| NetworkTargetProductServerDataSuppport networkTargetDataSupport; | ||
|
|
||
| NetworkLocationProvider networkLocationProvider; | ||
| NetworkTargetInfo currentNetworkTargetInfo; | ||
| String traceLogIdAsString; | ||
| Set<String> codeUploadFileSytemFolderPathes; | ||
|
|
||
| abstract class AbstractInstallSetupProductExecutor{ | ||
| # <I extends InstallSetup> I getInstallSetup() | ||
| } | ||
| interface ProductExecutor | ||
| interface InstallSetup{ | ||
| + boolean isAbleToScan(TargetType targetType) | ||
|
|
||
| ProductExecutorData ..>NetworkLocationProvider | ||
| ProductExecutorData ..>NetworkTargetProductServerDataProvider | ||
| ProductExecutorData ..>NetworkTargetInfo | ||
|
|
||
|
|
||
| abstract class AbstractProductExecutor{ | ||
|
|
||
| # abstract void customize(ProductExecutorData data); | ||
| # abstract List<ProductResult> executeByAdapter(ProductExecutorData data) | ||
| } | ||
| interface TargetResolver | ||
| class TargetRegistry | ||
| class SecHubWebScanConfiguration | ||
| class SecHubInfrastuctureScanConfiguration | ||
|
|
||
| class Target{ | ||
| + getURI() | ||
| + getIP() | ||
| + TargetType getType() | ||
| AbstractProductExecutor -> ProductExecutorData : creates + customizes | ||
| AbstractProductExecutor --> NetworkTargetResolver | ||
|
|
||
| note top of AbstractProductExecutor | ||
| The base class for mostly all product executors (except for Sereco). | ||
| The child classes must implmemnt the `customize` method and | ||
| configure the product executor data object accordingly. | ||
|
|
||
| It will handle automatically target specific parts | ||
| for scan types where it is necessary (WebScan, InfraScan). | ||
|
|
||
| All other scan types (e.g. CodeScan) do not | ||
| need to setup specific product executor data | ||
| (like NetworkLocationProvider). | ||
|
|
||
|
|
||
| end note | ||
| interface NetworkTargetProductServerDataProvider { | ||
| String getIdentifierWhenInternetTarget(); | ||
|
|
||
| String getIdentifierWhenIntranetTarget(); | ||
|
|
||
| String getBaseURLWhenInternetTarget(); | ||
|
|
||
| String getBaseURLWhenIntranetTarget(); | ||
|
|
||
| String getUsernameWhenInternetTarget(); | ||
|
|
||
| String getUsernameWhenIntranetTarget(); | ||
|
|
||
| String getPasswordWhenInternetTarget(); | ||
|
|
||
| String getPasswordWhenIntranetTarget(); | ||
|
|
||
| boolean isHavingUntrustedCertificateForIntranet(); | ||
|
|
||
| boolean isHavingUntrustedCertificateForInternet(); | ||
| } | ||
| class TargetData{ | ||
| + TargetType getTargetType() | ||
| + Set<URI> getTargetURIs() | ||
| + Set<InetAddress> getTargetIPs() | ||
|
|
||
| interface NetworkLocationProvider{ | ||
| List<URI> getURIs(); | ||
|
|
||
| List<InetAddress> getInetAdresses(); | ||
| } | ||
| enum TargetType { | ||
| INTERNET | ||
| INTRANET | ||
| CODE_UPLOAD | ||
| ILLEGAL | ||
| UNKNOWN | ||
|
|
||
| interface NetworkTargetResolver{ | ||
| + NetworkTarget resolveTarget(URI uri); | ||
| + NetworkTarget resolveTarget(InetAddress inetAdress); | ||
| } | ||
|
|
||
| ProductExecutor <|-- AbstractInstallSetupProductExecutor | ||
| AbstractInstallSetupProductExecutor o-- TargetResolver : uses | ||
| AbstractInstallSetupProductExecutor o-- AbstractAdapterConfigBuilder: uses | ||
| AbstractInstallSetupProductExecutor o-- Adapter: calls the adapter with created config | ||
| AbstractInstallSetupProductExecutor "1" - "1" InstallSetup : implementation will \nhave this injected | ||
| AbstractInstallSetupProductExecutor --> InstallSetup : reads | ||
| AbstractInstallSetupProductExecutor *-- TargetRegistry: creates and uses | ||
|
|
||
| TargetRegistry "1" *-- "n" Target : contains | ||
| TargetRegistry --> TargetData : provides | ||
| TargetResolver "creates" --> Target | ||
| Target *-- TargetType | ||
| Target "1" *-- "0..1" URI | ||
| Target "1" *-- "0..1" InetAdress | ||
| AbstractInstallSetupProductExecutor --> SecHubConfiguration : reads | ||
|
|
||
| SecHubConfiguration *-- SecHubWebScanConfiguration | ||
| SecHubConfiguration *-- SecHubInfrastuctureScanConfiguration | ||
| SecHubConfiguration *-- SecHubCodeScanConfiguration | ||
|
|
||
| SecHubWebScanConfiguration "1" *-- "n" URI | ||
| SecHubInfrastuctureScanConfiguration "1" *-- "n" URI | ||
| SecHubInfrastuctureScanConfiguration "1" *-- "n" InetAdress | ||
|
|
||
| note top of TargetResolver: Resolves information on given IP or URI.\nDetermines also the TargetType.\nSo dedicated installation setup can be used | ||
| note bottom of TargetData: Contains information for a \ndedicated TargetType which\ncan be used to call the adapter | ||
|
|
||
| note top of AbstractInstallSetupProductExecutor: This abstract implementation is able to automatically call\nadapter for multiple targets with correct setup data.\n\nE.g.a netsparker product executor uses its injected\nNetsparkerInstallationSetup and differs Intranet and \nIntranet by different agentgroups | ||
| note top of InstallSetup : The install setup contains the information about \nservers, usernames, passwords etc. for the\ncalling of the adaper | ||
| 'package NetworkTarget-internal as "If network target handling necessary for this executor" { | ||
| class NetworkTarget{ | ||
| + getURI() | ||
| + getInetAdress() | ||
| + NetworkTargetType getType() | ||
| } | ||
|
|
||
| note top of NetworkTarget | ||
| Represents a network target | ||
| to use for a dedicated network type | ||
| end note | ||
|
|
||
| enum NetworkTargetType { | ||
| INTERNET | ||
| INTRANET | ||
| ILLEGAL | ||
| UNKNOWN | ||
| } | ||
|
|
||
| class NetworkTargetRegistry | ||
|
|
||
| class NetworkTargetInfoFactory { | ||
| + NetworkTargetInfo createInfo() | ||
| } | ||
|
|
||
| class NetworkTargetInfo{ | ||
| + NetworkTargetType getNetworkTargetType() | ||
| + Set<URI> getNetworkTargetURIs() | ||
| + Set<InetAddress> getNetworkTargetIPs() | ||
| } | ||
|
|
||
| note top of NetworkTargetInfo | ||
| Represents (final) information about which | ||
| URIs /IPs are for a dedicated network | ||
| target type (e.g. INTERNET). | ||
| end note | ||
| '} | ||
|
|
||
| ' package NetworkTargetDataSupport-Internal as "Network target data Support" { | ||
|
|
||
| interface NetworkTargetProductServerDataProvider | ||
| class NetworkTargetProductServerDataSuppport{ | ||
| +String getIdentifier(NetworkTargetType target) | ||
| +boolean isAbletoScan(NetworkTargetType target) | ||
| +String getBaseURL(NetworkTargetType type) | ||
| +String getUserId(NetworkTargetType type) | ||
| +String getPassword(NetworkTargetType target) | ||
| } | ||
| ' } | ||
|
|
||
|
|
||
| NetworkTargetInfoFactory --> NetworkLocationProvider : uses | ||
| NetworkTargetInfoFactory --> NetworkTargetProductServerDataSuppport : uses data support | ||
|
|
||
| ProductExecutor <|-- AbstractProductExecutor | ||
| AbstractProductExecutor --> NetworkTargetProductServerDataSuppport: create+use (if necessary) | ||
| AbstractProductExecutor --> NetworkTargetInfoFactory: create+use (if necessary) | ||
| AbstractProductExecutor ..> NetworkTargetInfo | ||
|
|
||
| NetworkTargetInfoFactory -> NetworkTargetRegistry: internally created + used | ||
| NetworkTargetProductServerDataSuppport -> NetworkTargetProductServerDataProvider: uses | ||
| NetworkTargetInfoFactory o-- NetworkTargetResolver : uses | ||
|
|
||
| NetworkTargetRegistry "1" *-- "n" NetworkTarget : contains | ||
| NetworkTargetRegistry --> NetworkTargetInfo : provides | ||
| NetworkTargetResolver --> NetworkTarget | ||
| NetworkTarget *-- NetworkTargetType | ||
|
|
||
| note top of NetworkLocationProvider | ||
| Data normally comes from | ||
| sechub configuration | ||
| end note | ||
| note top of NetworkTargetProductServerDataProvider | ||
| Data normally comes from an | ||
| install setup | ||
| end note | ||
|
|
||
| @enduml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
52 changes: 27 additions & 25 deletions
52
sechub-doc/src/docs/asciidoc/documents/shared/concepts/concept_targets.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,29 +1,31 @@ | ||
| // SPDX-License-Identifier: MIT | ||
| For some security products it's necessary to differ between INTRANET scans and | ||
| INTERNET scans. This is called `Target`. | ||
| For some security products it's necessary to differ between `intranet` and `internet` scan targets. | ||
| This is represented by the class `NetworkTarget`. | ||
|
|
||
| Maybe the next UML looks a little bit `overwhelming` but it has a reason: | ||
| Some products are not able to handle different targets when not being installed | ||
| twice, some can do this by some settings etc. {sechub} must be able to automatically call the correct product installation | ||
| in such cases. To handle this always the same | ||
| way some framework mechanism was introduced, see next chapter: | ||
| Some products are not able to handle different network targets when not being installed | ||
| twice, some can do this by a product specific identifier. {sechub} must be able to | ||
| automatically call the correct product installation in such cases. | ||
|
|
||
| To handle this always the same way some framework mechanism was introduced, see next chapter. | ||
|
|
||
| [[sechub-concept-installsetup]] | ||
| ==== Automatic Target resolving and calling of adapters | ||
| // see http://plantuml.com/class-diagram for information about PLANT UML syntax | ||
| // see https://asciidoctor.org/news/2014/02/18/plain-text-diagrams-in-asciidoctor/ for link syntax | ||
| // TODO ATR, 2018-05-09: think about generating some parts here, directly from code instead of typing manually (in future) | ||
| plantuml::diagrams/diagram_target_architecture.plantuml[format=svg, alt="Class diagram of target and install setup architecture"] | ||
|
|
||
| The `AbstractInstallSetupProductExecutor` simplifies implementations of upcoming product implementations very much. | ||
|
|
||
| It's able to automatically decide | ||
| which target types are wanted to be scanned and automatically trigger calls to implementation for each target type but also with filter uris and ips, | ||
| and environment specific parts available by `Install Setup`. It also handles missing setup / unability to scan a target. Currently it will do a simple error logging | ||
| when a wanted target cannot be handled by the installation setup. | ||
|
|
||
| NOTE: For an example: | ||
| A `Nessus` installation is currently done twice: One for *internet* and one for *intranet*. | ||
| The implementation of NessusProductExecutor does not need to check which of the installation must be used, | ||
| which password etc. This all done by this abstract implementation. The same for `NetsparkerProductExecutor`, but there | ||
| we got only ONE installation - separation is done by agentgroups, but this is also handled automatically. | ||
| ==== Automatic Network Target info resolving | ||
|
|
||
| The class `AbstractProductExecutor` is the single base class for mostly all product executors and does | ||
| automatically provide network target handling for scan types `webScan` and `infraScan`. | ||
|
|
||
| The abstract executor will create a `ProductExecutorData` object at runtime let child implementations | ||
| customize it and then prepare all necessary stuff before giving it again to the child implementation | ||
| for final execution. | ||
|
|
||
| For automated target handling the customization of `ProductExecutorData` must set a | ||
| `NetworkTargetProductServerDataProvider` and a `NetworkTargetLocationProvider`. | ||
|
|
||
| [TIP] | ||
| ==== | ||
| For `PDS` the network target type will be injected to the `PDS` caller scripts automatically via | ||
| environment variable `PDS_SCAN_TARGET_TYPE`. Also `PDS` instances have the possibility to forbid | ||
| a target type - so for different target types we can define two different PDS executor configurations. | ||
| ==== | ||
|
|
||
| plantuml::diagrams/diagram_target_architecture.plantuml[format=svg, alt="Class diagram of target and install setup architecture"] |
7 changes: 6 additions & 1 deletion
7
...iontest/src/test/resources/sechub-integrationtest-client-sourcescan-generic-template.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,15 @@ | ||
| { | ||
| "apiVersion" : "{{ .SHTEST_VERSION }}" , | ||
|
|
||
| "codeScan": { | ||
| "data" : { | ||
| "name" : "the-used-testfolders", | ||
| "fileSystem": { | ||
| "folders": ["{{ .SHTEST_FOLDERS1 }}"] | ||
| } | ||
| } | ||
|
|
||
| "codeScan": { | ||
| "use" : [ "the-used-testfolders"]] | ||
| } | ||
|
|
||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters