-
Notifications
You must be signed in to change notification settings - Fork 9
Correlator User Guide
See the Correlator Installation Guide for information on setting up the ASTAM Correlator for the first time.
Open your browser of choice and navigate to http://localhost:8080/threadfix
(port and endpoint may change depending on your configuration). Your browser will display a a warning screen
about the SSL certificate. ThreadFix generates a unique self-signed SSL certificate when it first
starts up. You need to add the certificate to your list of trusted certificates to continue.
You will be presented with a sign-in page. The credentials for the built-in admin account are user and
password. These should be changed immediately.
After signing in you will be asked to add a Team. Before adding an application for scanning, we must create a team that owns the application. Enter the name of your team and click "Add Team".
A project is owned by a team; however, users are not assigned to a team or a project. Users simply provide access to the interface, while Teams allow you to organize your projects as necessary.
While signed in as an administrator, click the Settings gear in the top right and select Administration -> Users.
You will be brought to the Manage Users page. Users can be created, deleted, and edited within this page. Click Create User and complete the following form to create a new user.
All registered users have administrative privileges.
Click Add Application on the team directory to assign an application to your team. This will display a popup with various fields to enter. The required fields are:
Criticality - The importance of an application compared to other applications registered with the correlator, used for organization by the user
-
None- Unrecognized framework, scan merging will not be performed -
Detect- Attempt to auto-detect the framework type of the application JSPRAILSSPRING_MVCSTRUTSDOT_NET_MVCDOT_NET_WEB_FORMS-
PYTHON(Django framework)
Source Code Information - Click this link to display more options. This must be filled out in order to correlate static and dynamic scans
You can specify the code location on local disk or you can provide the repository to pull the code from. The following behavior can be expected depending on this configuration:
- Only defining local code path - The code on that path will be used as the source code for the project. Updating with the latest code requires updating the code at that path.
- Only defining repository information - A temporary copy of the repository will be cloned upon save and upon scanning.
- Defining local code path and repository - The local code path will be ignored.
Specifying a local code path and repository type (Git, SVN) without repository information will cause the local code path to be used, but the Correlator will attempt to pull the repository upon each scan. Since no remote or credentials are available, the pull will fail after a timeout. This will lengthen scan import times.
-
Source Code Repository Type- Specify the SCM type of your application -
Source Code URL- A link to the remote repository containing your source code. IfSource Code Repository Typeis set, this will automatically be pulled when a scan is uploaded -
Source Code Branch- The branch of the remote repository to pull from. If blank,masterwill always be used -
Source Code Revision- The ID of the commit to use when pulling from the given repository. If blank, the latest commit will always be used -
Source Code User Name- The username to use when authenticating against the remote repository -
Source Code Password- The password to use when authenticating against the remote repository -
Source Code Folder- The path to the copy of the source code on the server running ThreadFix. Repository information can be ignored if a copy is available on the ThreadFix server and this path is defined
Disable Vulnerability Merging - Prevents the ASTAM Correlator from merging SAST and DAST scans for the given project
These settings can be changed after creating your application by navigating to the application's overview page by
clicking the Action drop-down and selecting Edit / Delete.
Once an application has been added, it should appear on the Teams page listed under the team you created in the previous step.
Click on an application in the Teams page to view the application's overview page. Click the Action drop-down
and select Upload Scan. A file picker dialog will appear. Select your SAST or DAST scan associated with the
given application.
The supported scan formats match those of the original ThreadFix software:
- https://github.com/denimgroup/threadfix/wiki/Static-Scanners
- https://github.com/denimgroup/threadfix/wiki/Dynamic-Scanners
Click OK, and the webpage will display a loading dialog. The import process may take a while depending on the size of the codebase, the number of imported vulnerabilities, and whether or not the application source needs to be pulled from a Git repository. Once imported, the page will update and display all of the imported vulnerabilities, organized by type and severity.
These entries can be expanded to display the available information regarding the vulnerabilities. This may include the vulnerable URL, source code file, and query parameters. Scan findings that have been merged will display both a URL and a path to the source code that generated a vulnerable response. Unmerged scans will display only one or the other.
Any number of scans may be uploaded for the same application. The ASTAM Correlator will automatically merge duplicate vulnerabilities and combine their available information to provide a more detailed view into the vulnerability.
The ASTAM Correlator can be configured to use a Git or SVN repository when gathering source code. This setting must be managed in the properties page for an Application.
If an SCM is used as the source code location, the repository will be pulled for each scan uploaded for the application. This can greatly increase scan times for larger projects.
An application configured to use a Git repository as its source code location will require extra time to pull this source code when running a scan. Git Monitoring can be configured to automatically check the repository for the most recent updates and pull the latest version if necessary.
Settings for monitoring Git repositories can be managed by navigating to an Application's overview page, clicking the Action dropdown button, and selecting Manage Repository Monitor. A popup will display giving the option to:
- Enable or disable Git monitoring
- Specify when and how often the Git repository should be checked for changes
Change the settings as desired and click Save to finish configuration.
Being a derivative of Denim Groups' ThreadFix software, various features have carried over. These are:
| Feature | Wiki Link | Remarks |
|---|---|---|
| Remote Providers | https://github.com/denimgroup/threadfix/wiki/Remote-Providers | |
| Command Line Interface | https://github.com/denimgroup/threadfix/wiki/Command-Line-Interface | Needs to be built from source |
| Adding Manual Findings | https://github.com/denimgroup/threadfix/wiki/Manual-Findings | |
| SSVL Converter | https://github.com/denimgroup/threadfix/wiki/SSVL-Converter | Needs to be built from source |
| REST Interface | https://github.com/denimgroup/threadfix/wiki/ThreadFix-REST-Interface |
Errors that occur while using the web interface can be found in the Errors page available to all users.
While logged in, click the Settings gear in the top right and select Error Messages. Error logs output by the ASTAM Correlator can be viewed here.
If the error log does not provide enough information or an error occurs before the web interface is available, you can manually inspect the complete log file using tail /opt/tomcat/logs/astam.log on the hosting server.
This material is based on research sponsored by the Department of Homeland Security (DHS) Science and Technology Directorate, Cyber Security Division (DHS S&T/CSD) via contract number HHSP233201600058C.