Merge pull request #1084 from blackducksoftware/cp_IDETECT-4274_doc

cpottsbd · web-flow · commit f50bd05614b2 · 2024-04-08T16:07:46.000-04:00
Cp idetect 4274 doc
diff --git a/documentation/keywords.ditamap b/documentation/keywords.ditamap
@@ -6,6 +6,7 @@
   <keydef keys="division_name"><topicmeta><keywords><keyword>SIG</keyword></keywords></topicmeta></keydef>
   <keydef keys="binary_repo_type"><topicmeta><keywords><keyword>Artifactory</keyword></keywords></topicmeta></keydef>
   <keydef keys="solution_name"><topicmeta><keywords><keyword>Detect</keyword></keywords></topicmeta></keydef>
+  <keydef keys="threat_intel"><topicmeta><keywords><keyword>ReversingLabs</keyword></keywords></topicmeta></keydef>
   <keydef keys="source_project_name"><topicmeta><keywords><keyword>synopsys-detect</keyword></keywords></topicmeta></keydef>
   <keydef keys="bash_script_name"><topicmeta><keywords><keyword>detect9.sh</keyword></keywords></topicmeta></keydef>
   <keydef keys="powershell_script_name"><topicmeta><keywords><keyword>detect9.ps1</keyword></keywords></topicmeta></keydef>
diff --git a/documentation/src/main/markdown/components/tools.md b/documentation/src/main/markdown/components/tools.md
@@ -13,5 +13,6 @@ value specified in parentheses are:
 * [Vulnerability Impact Analysis Tool](../runningdetect/basics/runningwithblackduck.md) (--detect.tools=IMPACT_ANALYSIS)
 * [IaC Scanner](../runningdetect/basics/runningwithblackduck.md) (--detect.tools=IAC_SCAN)
 * [Container Scan](../runningdetect/containerscanning.md) (--detect.tools=CONTAINER_SCAN)
+* [ReversingLabs Scan](../runningdetect/threatintelscan.md) (--detect.tools=THREAT_INTEL)
 
 The detector tool runs any applicable [detectors](../components/detectors.dita).
diff --git a/documentation/src/main/markdown/currentreleasenotes.md b/documentation/src/main/markdown/currentreleasenotes.md
@@ -3,14 +3,6 @@
 ## Version 9.6.0
 
 ### New features
-* 
+* ReversingLabs Scans - this new feature provides analysis of software packages for file-based malware threats.
+	See [ReversingLabs Scans](runningdetect/threatintelscan.md) for further information.
 
-### Changed features
-* 
-
-### Resolved issues
-* 
-
-### Dependency updates
-
-* 
diff --git a/documentation/src/main/markdown/introduction.md b/documentation/src/main/markdown/introduction.md
@@ -2,7 +2,7 @@
 
 [company_name] [solution_name] is an intelligent scan client that analyzes code in your projects and associated folders to perform compositional analysis. [company_name] [solution_name] can be configured to send scan results to [blackduck_product_name], which generates risk analysis when identifying open-source components, licenses, and security vulnerabilities.
 
-[company_name] [solution_name] can be used in both connected and air gap modes.  
+[company_name] [solution_name] can be used in both connected and air gap modes depending on the types of scans being run.    
 
 ## [company_name] [solution_name] has the following characteristics.     
 
@@ -14,7 +14,7 @@
 
 * Runs on Windows, Linux, and macOS. It is available through GitHub, under the permissive Apache License, Version 2.0 and does not require pre-installation or extensive configuration.
 
-* Supports scanning Docker images by identifying open-source libraries and code within the images, using both signature scanning and the package manager analysis techniques.  
+* Supports scanning Docker images by identifying open-source libraries and code within the images, using both signature scanning and the package manager analysis techniques.    
 
 ## [company_name] [solution_name] functionality consolidation.   
 
@@ -34,7 +34,11 @@
 
 * Calculate security vulnerability risk in your code.
 
-* Produce reports of the open-source analysis findings.  
+* Produce reports of the open-source analysis findings.
+
+* Provide malware information if identified.   
+
+<note type="note">Some scan types require specific feature licenses to execute. Contact your [company_name] representative for further information.</note>
 
 ## How [company_name] [solution_name] functions.   
 
@@ -46,5 +50,4 @@ When looking at vulnerabilities in open source and third-party software, [compan
 
 * Uploads both sets of results (dependency details) to [blackduck_product_name] creating the project/version if it does not already exist. [blackduck_product_name] uses the uploaded dependency information to build the Bill Of Materials (BOM) for the project/version.
 
-* You can view the output and analysis results in [blackduck_product_name].  
-
+* You can view the output and analysis results in [blackduck_product_name].    
diff --git a/documentation/src/main/markdown/runningdetect/threatintelscan.md b/documentation/src/main/markdown/runningdetect/threatintelscan.md
@@ -0,0 +1,46 @@
+# [threat_intel] Scan
+
+[threat_intel] Scans are a way of running binary file analysis that provides malware warnings, with a risk analysis level applied, for open source and commercial software.
+
+[company_name] [solution_name] will accept a user provided local file path to a binary file for [threat_intel] Scan. This file may be a single executable, or a compressed file, such as a tar or zip, that contains many files for analysis.
+
+Identification of malware displayed to [blackduck_product_name] users will include file name, file path, and other identifiers, along with a description of the type of malware, and severity of the findings.
+
+## Workflow
+
+1. The file for scanning is uploaded to [blackduck_product_name] Storage service by [company_name] [solution_name].   
+1. Once uploaded, [threat_intel] service takes the file from Storage service and downloads it to its own container.   
+1. The [threat_intel] service invokes [threat_intel] tools to extract any archived files and generate file hashes.   
+1. [threat_intel] sends the SHA-1 hash of the uploaded file, along with hashes, and their size in bytes, of files extracted from any archives.
+1. Once complete, a report in JSON format is sent back to [threat_intel] service, which is then forwarded to [blackduck_product_name] Scan service. This report is saved in the [blackduck_product_name] database.   
+<note type="note">The scanned file is removed from Storage service when the scan completes, and [threat_intel] service does not persist any data for this file.</note>
+
+## Requirements and Limitations
+
+### General Requirements
+ * [blackduck_product_name] server must have the appropriate [threat_intel] license.
+ * [company_name] [solution_name] 9.6.0 or greater.
+ * Must be running [blackduck_product_name] 2024.4.0 or greater.
+ * The [threat_intel] service container (rl-service) must be running.
+ * [threat_intel] scans require network connectivity (Air gap mode is not supported).
+ * [threat_intel] scan does not provide project and version name defaults so you need to set project and version names via properties when [threat_intel] is the only tool invoked. (If the specified project or version does not exist in [blackduck_product_name], it will be created.)
+ 
+### Limitations
+ * [threat_intel] Scan is limited to images of 5GB or less for hosted services.
+ * [threat_intel] Scan is limited to images of 6GB or less for local, on-prem services.
+ 
+## Invocation
+To invoke a [threat_intel] scan, which only executes in "Intelligent" mode, the following must be provided at a minimum in addition to [blackduck_product_name] Server related configuration properties:   
+ ```
+--detect.tools=THREAT_INTEL
+--detect.threatintel.scan.file.path=<Path to local binary file>
+--detect.project.name=<Use existing or set as a value to be created>
+--detect.project.version.name=<Use existing or set as a value to be created>
+```
+ 
+## Results
+
+[threat_intel] scan findings will appear in the [blackduck_product_name] user interface under the **Malware** tab. Further information on viewing [threat_intel] results is available [here](https://sig-product-docs.synopsys.com/bundle/bd-hub/page/ComponentDiscovery/aboutReversinglabsScanning.html)
+
+## Further information
+For additional information regarding the related properties, see [threat-intel](../properties/configuration/threat-intel.md)
diff --git a/documentation/topics.ditamap b/documentation/topics.ditamap
@@ -34,17 +34,17 @@
 	<topicref href="gettingstarted/quickstart.md" format="markdown"/>
 	<topicref href="gettingstarted/overview.md" format="markdown">
 		<topicref href="gettingstarted/terms/intro.md" format="markdown">
-			<topicref href="gettingstarted/terms/sca.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/run.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/script.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/jar.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/tools.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/bdio.md" format="markdown"/>
 			<topicref href="gettingstarted/terms/detectors.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/properties.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/impactanalysis.md" format="markdown"/>
 			<topicref href="gettingstarted/terms/inspectors.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/jar.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/properties.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/run.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/sca.md" format="markdown"/>
 			<topicref href="gettingstarted/terms/scans.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/bdio.md" format="markdown"/>
-			<topicref href="gettingstarted/terms/impactanalysis.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/script.md" format="markdown"/>
+			<topicref href="gettingstarted/terms/tools.md" format="markdown"/>
 		</topicref>
 		<topicref href="gettingstarted/howitworks.md" format="markdown"/>
 		<topicref href="gettingstarted/workflow.md" format="markdown"/>
@@ -87,17 +87,18 @@
 			<topicref href="runningdetect/includingexcluding/pkgmgrs.md" format="markdown"/>
 			<topicref href="runningdetect/includingexcluding/directories.md" format="markdown"/>
 		</topicref>
+		<topicref href="runningdetect/component-location-analysis.md" format="markdown"/>
+		<topicref href="runningdetect/concurrent.md" format="markdown"/>
+		<topicref href="runningdetect/containerscanning.md" format="markdown"/>
 		<topicref href="runningdetect/detectorcascade.md" format="markdown"/>
-		<topicref href="runningdetect/statelessscan.md" format="markdown"/>
-		<topicref href="runningdetect/rapidscan.md" format="markdown"/>
 		<topicref href="runningdetect/iacscan.md" format="markdown"/>
-		<topicref href="runningdetect/runningairgap.md" format="markdown"/>
-		<topicref href="runningdetect/status-file.md" format="markdown"/>
 		<topicref href="runningdetect/proxies.md" format="markdown"/>
-		<topicref href="runningdetect/concurrent.md" format="markdown"/>
-		<topicref href="runningdetect/containerscanning.md" format="markdown"/>
+		<topicref href="runningdetect/rapidscan.md" format="markdown"/>
 		<topicref href="runningdetect/runincontainer.md" format="markdown"/>
-		<topicref href="runningdetect/component-location-analysis.md" format="markdown"/>
+		<topicref href="runningdetect/runningairgap.md" format="markdown"/>
+		<topicref href="runningdetect/statelessscan.md" format="markdown"/>
+		<topicref href="runningdetect/status-file.md" format="markdown"/>
+		<topicref href="runningdetect/threatintelscan.md" format="markdown"/>
 	</topicref>
 	<topicref href="components/overview.md" format="markdown">
 		<topicref href="components/tools.md" format="markdown"/>
