# Getting Started Before you dive into the documentation, please take a minute to understand how our docs are structured. ### Quick Start Our [Quick Start](/developer-quickstart) documentation will guide you through the process to get you up and running with Threatrix scans ASAP. The goal is to start with simple tasks and build upon that foundation towards full integration and automation. ### Threat Center [Threat Center](/threat-center-1/creating-account) is the dashboard that allows you to review your project scan results, fix vulnerabilities, and administer the platform. You must create an account or be invited by another user to access Threat Center. ### Threat Agent Threatrix [Threat Agent ](/threat-agent/threat-agent-1)is a command line tool useful for automating your scans from within your DevOps processes. It seamlessly integrates with your build server to effectuate scans and enforce policies as they apply to your build. ### Build Integration Start here when you are ready to get started with full scan automation. We make it easy to integrate our [Threat Agent](/threat-agent/threat-agent-1) into any build environment to automate your project scans quickly. ### Policy Management [Policies](/policy-management/policy-overview) allow your legal and security teams to enforce the governing rules within your Organization, Entity, or Project. Policies drive actions like Alerts, build failures, component version changes, and automated license annotation. ### Administration If you hold administrative supers powers, this is your secret lair. You have the power to add and remove users, modify permissions and build customer roles in [RBAC](/administration/rbac). You can also create and manage the entities and administer notification settings. # Developer Quick Start Scan your first project with just a few clicks. ### 1) Create an account The easiest way to scan your project is by authenticating using Github or Gitlab. [OAuth login](/threat-center-1/creating-account/oauth-login). This enables you to have immediate access to your projects. Alternatively, you can scan your project using our [Threat Agent](/threat-agent/threat-agent-1). ### 2) Scan your project using ThreatScan Once you've authenticated using OAuth, you will access your repositories from within our [ThreatScan dashboard](/securecore/threatscan). ### 3) Reviewing scan results Scan status will be available in the lower right-hand corner of your screen. ![](/files/-MiSWJULV2L_-B8uZcyN) Once the scan has been completed, a link to the [scan results](/securecore/scan-results) will appear in the status bar for up to 20 seconds. ![](/files/-MiSWkgU7LstCpx2H-G-) Completed scan results will also be available from within the [Entity](/resources/dictionary#entity) dashboard. That's typically, but not always, your default Entity, which can be reached by clicking "My Team" on the top menu bar and then clicking the "Projects" tab. ![](/files/-MixEhVTjk3OrCcvQp6M) {% hint style="info" %} For more information, see our full documentation on reviewing [scan results](/securecore/scan-results). {% endhint %} # SecureShip # Artifactory Scanning Sample container registary setup

Navigate to

# ThreatAgent Scanning ### Container Scanning examples Run container image scan: 1. Private DockerHub image ``` java -jar ./threat-agent.jar \ --oid=a4d2ca7c-5114-4441-87bc-0a9ec5874750 \ --eid=d9b27057-6034-4360-9ae4-c6a8275af380 \ --registry-login=username --registry-password=password --api-key=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaXRodWdWItTURRNlZYTmxjak16TWpZNE1qRXgiLCJleHAiOjE2NTcwNzQyMzksImlhdCI6MTY0MTQzNTgzOX0.P3VUxrh86I9NDwC9Q5X3mTuDWrgl7Xh_pxGeR6GP8OM \ image:docker.io/sonarqube:9-community ``` 2. Image from local DockerEngine ``` java -jar ./threat-agent.jar \ --oid=a4d2ca7c-5114-4441-87bc-0a9ec5874750 \ --eid=d9b27057-6034-4360-9ae4-c6a8275af380 \ --api-key=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaXRodWdWItTURRNlZYTmxjak16TWpZNE1qRXgiLCJleHAiOjE2NTcwNzQyMzksImlhdCI6MTY0MTQzNTgzOX0.P3VUxrh86I9NDwC9Q5X3mTuDWrgl7Xh_pxGeR6GP8OM \ image:threatrix/base:latest ``` 3. Public DockerHub image ``` java -jar ./threat-agent.jar \ --oid=a4d2ca7c-5114-4441-87bc-0a9ec5874750 \ --eid=d9b27057-6034-4360-9ae4-c6a8275af380 \ --api-key=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaXRodWdWItTURRNlZYTmxjak16TWpZNE1qRXgiLCJleHAiOjE2NTcwNzQyMzksImlhdCI6MTY0MTQzNTgzOX0.P3VUxrh86I9NDwC9Q5X3mTuDWrgl7Xh_pxGeR6GP8OM \ image:sonarqube:10-community ``` 4. Private GitHub Container Registry image ``` java -jar ./threat-agent.jar \ --oid=a4d2ca7c-5114-4441-87bc-0a9ec5874750 \ --eid=d9b27057-6034-4360-9ae4-c6a8275af380 \ --registry-login=username --registry-password=password --api-key=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaXRodWdWItTURRNlZYTmxjak16TWpZNE1qRXgiLCJleHAiOjE2NTcwNzQyMzksImlhdCI6MTY0MTQzNTgzOX0.P3VUxrh86I9NDwC9Q5X3mTuDWrgl7Xh_pxGeR6GP8OM \ image:ghcr.io/threatrix/threatrix-base:latest ```
# Creating Account You must create an account before you're able to scan your projects. A Threat Center account provides access to your profile, scan results data, auto-remediation, capabilities, and API keys. ### OAuth Authentication Threat Center supports Github, Gitlab and Bitbucket SCM Authentication, and Google. OAuth SCM is the recommended authentication mechanism for Threat Center. It offers numerous advantages including: * More secure than Standard Authentication * Automatic account creation * No need to remember your username/password * Immediate access to your repositories for scanning * Ability to log in, access all of your repositories, and run scans across Github, Gitlab, and Bitbucket from within a single Threat Center account. Read Full [OAuth authentication documentation](/threat-center-1/creating-account/oauth-login) ### Standard Authentication Standard username/password authentication allows users access to Threat Center without using our recommended OAuth authentication option User the link below to create an account using standard authentication. {% embed url="" %} ### Inviting Users to Join Threat Center Users may invite other users to join Threat Center. An `Invite User` link is available from your profile. Click the link to invite your colleagues to Threat Center. ![](/files/-MiTOYy0h2Qatm5MGVsz) From the Invite User screen, you'll have the option to copy the invite URL or to have it sent separately. (slack sounds like a good idea), or fill in a comma-delimited list of email addresses for the users you want to invite. The URL link may be used by multiple users to activate their account. {% hint style="info" %} Invited users will be assigned to the same Entity (Business Unit) as the party who sent the invite. The entity may be changed by a user with the appropriate permissions, from within the [User Administration](/administration/add-users) screen. {% endhint %} ![](/files/-MiTPBsWcMIL_DyTm2SD) # OAuth Login OAuth login allows your team to both easily authenticate into Threat Center and integrate your SCM repositories for scanning directly from ThreatScan. ## Authentication Using Multiple OAuth Accounts If you choose to log in to Threat Center using more than one authentication method, only one account will be created within Threatrix. This allows for access to multiple repositories through your single Threat Center account. Once authenticated from within the [ThreatScan](/securecore/threatscan) dashboard, you have the option to select a source repository from the available SCM integrations. {% hint style="warning" %} Please note: during our Beta phase, only Github OAuth login will be available. {% endhint %} The easiest way to scan your project is by authenticating using Github or Gitlab [OAuth login](/threat-center-1/creating-account/oauth-login). This enables you to have immediate access to your projects. ![](/files/-MiSRgEgSTYywtO5kE_y) # Entity Dashboard Immediately after logging in to Threat Center you will be redirected to "My Team", which is your home entity dashboard. ### Overview The [Entity](/resources/dictionary#entity) dashboard organizes and controls the people, processes, projects, and policies for the users assigned to the entity and subordinate entities. The Entity dashboard is divided into two sections 1. **CHARTS** 2. **TEAMS, PROJECTS & TEAM TREE** ![](/files/-MiZGzDHjKr5NCRIcS0W) ### Charts Charts reflect an aggregate of all scan data, for every project of every entity subordinate, to the current entity. The charts provide a single pane of glass to quickly assess risk across multiple dimensions of the entity, including both vulnerability and license risks. Cross-dimensional data is available from the dropdowns. The data for the selected dimension is shown in the timeline stack chart to provide a history of risk for the selected dimension. ![Aggregated scan data across all subordinate entities (click to enlarge)](/files/-MiZMOcRmrh8o-OtM_Br) ### Teams, Projects, and Org Tree #### Teams Tab Subordinate Entities are organized as a list under Teams. We will display teams up to 3 subordinate levels deep. In the example shown below, the organization has set up teams for their major and minor geographical regions. This design allows for the management and organization of larger volumes of scan data. The sparkline charts allow, at a glance, to determine the origin of your risk. Clicking a subordinate entity will take you directly to the entity's dashboard to evaluate its risk in detail. {% hint style="info" %} The Teams tab is only displayed when an Entity has subordinated entities. {% endhint %} ![](/files/-Mib1G_9RXK003ljdQoD) ### Projects The projects tab displays projects directly attached to this entity. Vulnerability, license risk, and asset composition metrics from the most recent scan are displayed in the summary columns, with the last scan timestamp. ![](/files/-Mib3nPx48xHP-ljlXk5) ### Team Tree Team tree is an alternative view of your teams. The menu on the right provides the option to see the chart on a full screen. ![Team Chart (click to enlarge)](/files/-Mib9Tjm0kWptDPy3-YN) ![Full screen Team Chart (click to enlarge)](/files/-Mib9lrLubmujErVSqBz) # User Profile ### Location The User profile is available through the User Profile icon in the top right corner of Threat Center. Clicking the icon will display a drop-down menu with options. ![](/files/-Mirqu9rOr0il6H13cDK) Selecting Profile will redirect the user to their profile from which they will have access to metadata associated with their account. ![](/files/-Mirr8QVrDcY3RVLhodV) ### Organization Organization name and OrgID are displayed on the left side of the user profile, shown below. OrgID is required for integration with external tooling. ![](/files/-MirsbtpwKK9Nnt2tzRd) ### Entities Users may be assigned to one or more entities within an organization. Entity assignments are assigned based on the entity assignment of the user who invited them to Threatrix or when an administrator creates your account. EntityID values are used with integrated tooling to choose which Entity the scan results for a project will be assigned. ![](/files/-MirsmfpAZs2Y9VT8Goi) ### Roles User roles are assigned by your organization's administrator and are displayed with the Roles tab. If you possess ADMIN or SUPER ADMIN privileges, you may modify your own role and privileges. ![](/files/-Mis4A3iHX9Y6BjHZE3m) ### API Keys API Keys are required for access to the [Threatrix API](/graphql-api/api-overview). ![](/files/-Mis4_c2xt3zHdh_xO5p) Adding a new user API key: Clicking "Add API Key" will take you to a screen that allows you to create a new API Key. Add a title based on the keys' intended usage and an optional description and click Generate API Key. API Keys are valid for a period of one year or until deleted or marked as invalid by an Administrator. ![](/files/-Mis4tN3ZU8_QD6iivZ8) ### SCM Accounts Source control manager (SCM) accounts, while not required, are used throughout the Threatrix platform to perform actions on behalf of the user including scanning, creation of pull requests and viewing snippets in the SIMM tool. In order to use these various features you'll either need to use the OAuth login for your SCM, from the login screen or add an SCM account by manfully creating a token and adding it here. #### GitHub Permissions For PUBLIC ONLY repository access ``` public_repo, read:org, read:user, user:email, workflow ``` For PUBLIC & PRIVATE repository access ``` repo, read:org, read:user, user:email, workflow ``` #### GitLab Permissions ``` api, read_user, read_repository, write_repository ``` #### Bitbucket Permission ``` email, account, repository:write, pullrequest:write ``` # Reviewing Results # Quick Start ## Creating A CodeCertify Project ## Project Structure AICertify and CodeCertify projects are structured in a way that allows our customers to build projects that represent real world products. In the real world, software-based products are constructed from various source of code that must all come together to create a release for a given product. AICertify and CodeCertify projects allow your team to aggregate all of these various sources of code that make up a given release. Each source is known as a **module.** Modules are first class citizens from which you can perform review actions, generate reports and apply specific policy that make meeting security, compliance and regulatory requirements much faster and easier. Modules can be added to \*Certify projects from various sources, including: * Importing source code or binary projects from upstream vendors * Public and private Source Code Repositories * Public and private Container Repositories Consider a very simple Infotainment System may contain modules from various vendors that make up the functionality in that System. Your team can each of the modules to a project that enbales them to see the various aspect of legal and security risk and enable them to take action, create policy and engage directly with the engineering team to mitigate various risks. ## Project Summary Tab The project summary tab provides a glimpse into the review status of of your project, and both license and security risks associated with those modules. A sumary of all discovered licenses and vulnerabilities are available from this pane. [**Learn more here**](#project-summary-tab)

## Components Tab CodeCertify components tab displays scan results for artifacts that are declared in dependency files(POM, NPM, etc), discovered libraries that are included with the project(zip, tar, nupkg, deb, jar, etc) and source-based libraries such as javascript CDN references or whole source components. [Learn more here](#components-tab)

## Assets Tab CodeCertify Assets tab displays the file(i.e source code, config files, dependency files, etc) artifacts in your project. The filters default to those source artifacts with a match to open source so that your team can quicklly determine the IP and legal risks from those artifacts. [Learn more here](#assets-tab)

# Project Summary Tab

## Project Modules Modules represent a unit of code that's part of the overall data that makes up a CodeCertify project. Modules help your team to understand, mange and report on more granular units of risk as part of the whole CodeCertify project. Modules are helpful because they also allow your team to create take actions and create policy for the module independent of the whole project.

### Adding a module A new module can be added by selecting the Add Moudle link shown at the top of the module pane. This produces a dialog that enables you to select the origin of the module. This is a contextual dialog and varies among Threatrix products.

The Drag and Drop options are available by default. \`Connect\` options will depend on your organizations configuration. If you have On Premise source control management systems that are not shown, those can be configured through the Admin panel. ### Deleting a Module Delete a module both removes it from your CodeCertify project and also deletes the underling SecureCore project represented by the module.

### Removing a Module Removing a module removes the module from the CodeCertify project but does not delete the underlying SecureCore project that's represented by the module.

### Moving a Module A module may also be moved to a different project, which may be helpful for various reasons.

Choosing to move a module will produce a dialog from which you can select the destination project denoted by AIC for AICertify projects and CC for CodeCertify projects.

## Branch and tag module alignment CodeCertify helps your team manage reporting associated by aggregating data across your modules. Aligned modules can then be used to generate currently and historical release reports to share with interested parties, like team members or regulators. This feature requires that your ThreatAgent(link) scan setup include both branch and tag information that will be used to populate the options in the respective drop down menus

CodeCertify branch and tag module scan alignment

By selecting s specific branch and tag, those modules containing scans configured with the respective branch and tag values will be selected across all modules. This allows your team to quickly create reports for a given release. {% hint style="danger" %} Only modules that contain scans with the selected values will be displayed and used for reporting. Be sure to double check the results to ensure all nececssary modules are included. {% endhint %} Once your aligned your modules, all reports will contain only the data from specific scan for each module. Simply select a report type to export the report.

## CodeCertify Project Review Status & Metrics CodeCertify projects allow your team to review artifacts to Approve, Reject or Ignore the artifacts in order to classify their risk and generate actionable policy. Summarized Review status metrics provide a useful measure of completion. By default, the review status reflects aggregated data for all modules included in the project.

## CodeCertify Module review status and meta data By selecting a module, you can view the review status for individual modules. When a module is selected, the Modules most recent scan meta data is also displayed.

## Module Menu Items ### Adding Module to a report By default, all modules in a project are exported to generated reports. However, one or more modules may be selected to create reports from a subset of the complete data for project by selecting the "Add to report" icon shown below.

### Scan History Scan history is kept forever, even beyond the end of time as we have made a pact with the universe to store data in the ether. Ok, not really, but we keep scan data until you fire us. You can see the complete scan history for a module by selecting the Scan Hisotry icon shown below.

### Re scan A module can be rescaned by clicking the Scan Again icon:

## Licenses By default, the licenses tab reflects a unique list of licenses across all modules. You can display the licenses for a single module by selecting the module in the left module pane.

## Vulnerabilities By default, the licenses tab reflects a unique list of licenses across all modules. You can display the licenses for a single module by selecting the module in the left module pane. # Components Tab # Custom Components ## What are Custom Components Custom components allow organizations to create and maintain a private knowledge base of component artifacts with their associated meta data such as versions, licenses and copyrights. ## How are Custom Components Used Custom Components can be used to automatically associate Custom Component data with components that were unmatched during a scan. Unmatched components happen for a variety of reasons, but your team may still need to account for an artifact that was unmatched by Threatrix. This is where Custom Components comes in handy. Custom Components are first class components that contain all of the necessary data that your team will need to account for any risk associated with the unmatched artifact, including licenses, copyrights and vulnerabilities. All of this data will be present on reports and risk management tools such SecureCore and Artifact Risk Graph(ARG). ## Important Notes Please read and understand some[ Important Notes](/codecertify/components-tab/custom-components/important-notes) regarding the creation, administration and application of Custom Components. # Adding ## Eligibility Only unmatched components are edible for assignment of a custom component. An unmatched component is one that was not found in our database using available matching techniques. ## Creating a custom component Custom components can be created from the Components tab by selecting an unmatched component and then clicking Add Component in the compont details window, on the right side.

This opens the "Add Component" window from which you can provide a the necessary meta data for your new component. Available fields are: * Component Name: The name of the component * Namespace: The namespace, if known * Version: The version, if known * PURL Type: This refers to the Ecosystem from which the component originated. Select NON\_PURL if the component is not from a known ecosystem, or UNKNOWN if you don't know from which ecosystem this component originated. * License(s): One ore more license scan be applied to the component. When you being typing, both the Threatrix knowledge base and your organizations license knowledge base will be searched for based on the value you've entered. * Copyrights: The free form copyright field allows you to add 1 or more copyrights to the component * Internal: Checking this box indicates that this is a proprietary, internal component and not open source or not 100% open source.

When you're done filling in the meta data details, simply click "Add Component" and the new component will be created in your organizations Component knowledge base and automatically associated with the unmatched component, as shown below:

Clicking the ![](/files/Qg2maZ33q5kZ7xnQgRht) icon will display the custom component dialog window with the following attributes: * Internal: Checking this box indicates that this is a proprietary, internal component and not open source or not 100% open source. * Copyrights: The free form copyright field allows you to add 1 or more copyrights to the component * License(s): One ore more license scan be applied to the component. When you being typing, both the Threatrix knowledge base and your organizations license knowledge base will be searched for based on the value you've entered. * PURL Type: This refers to the Ecosystem from which the component originated. Select NON\_PURL if the component is not from a known ecosystem, or UNKNOWN if you don't know from which ecosystem this component originated. * Version: The version, if known * Namespace: The namespace, if known * Component Name: The name of the component

## Important Notes Please read and understand some [Important Notes](https://app.gitbook.com/o/-MivlZ8lOmEOYjSRFOgb/s/-MbsieSiu0D66DBFP4uh/~/changes/304/codecertify/custom-component-management/important-notes) regarding the creation, administration and application of Custom Components. # Important Notes * Custom components are associated with the signature of the component from which is was created. * ALL other components with the same signature, across all projects in the organization, will be automatically associated with the new custom component on rescan * Editing the component details associated with a project will NOT alter the underlying custom component details. You must use the "[Editing Custom Components](https://app.gitbook.com/o/-MivlZ8lOmEOYjSRFOgb/s/-MbsieSiu0D66DBFP4uh/~/changes/304/codecertify/component-management/editing-custom-components)" feature in order to alter the custom components meta data. Therefore, if you edit the licenses, copyrights, version or origin of the custom component associated with the project, those changes will ONLY apply to the project and NOT apply to other components with the same signature, even after rescan. * While project component changes do not affect custom component meta data, changes to the custom component WILL affect organization scoped matching artifacts during the next scan. * Any changes to the custom component will ONLY be applied after rescan. # Header Panel ## License Details The license summary panel displays a unique list of discovered licenses based on the contents of data in the main panel. By default the root node of the project is selected which displays all discovered component licenses for all modules. However, selecting a module, node in the tree or a single file will filter the license list based on this context. Licenses are organized by risk and the the pie chart displays the number of unique license sthat fall into a given risk category. Hovering over the pie chart will display the associated risk category.

License names can be displayed by clicking the document icon in the upper right corner.

## Center Panel ### Review Metrics The top panel displays review status metrics to help your team determine the status of various artifacts during the review process. By default, all artifacts are pending review. The review status metrics are clicking and allow for the filtering of results by each status * A = Approved * R = Rejected * I = Ignored * P = Pending

### Component Type Metrics Threatrix detects two types of components during scans: * Dependencies: These are declared components and their transitive dependencies within discovered dependency files(ie, pom.xml, package.json, csproj). * Libraries: Libraries are standalone components that are discovered as part of the module scanning process. These are generally archives or binaries, such as nuget, jar, war, zip or rpm package that's an ordinary file. * Source components: You may also see components that are reflective of a source file that we deem to be a component. These are typically javascript discovered in HTML files that we determine to be a "release" of the component and therefore may contain vulnerabilities that would otherwise be unreported by other tools. These are currently categorized as a "Library" but may change in the future to allow customers to view these as standalone components. A full list of supported binaries can be[ found here.](/resources/binary-file-support) Letters indicate the following values * D = Dependency * L = Library

### Review All Section Reviewing artifacts can be time consuming. We've made every effort to provide tools, filters and review actions that reduce the time necessary to review artifacts in CodeCertify. The top panel review actions allow you to review all artifacts currently visible in your main panel. This enables your team to filter by specific criteria and then review all matching artifacts with a single click. Revert Last Action allows your team to rollback the last action that was completed.

### Filter Section Filters enable users to reduce the results based on factors that may help isolate risk to expedite the review process. User can filter on: * Component Name: Allows for filtering of components by component name. This filter uses the value entered for a similarity search and includes the component namespace, group and name. For example, a search for "amqp" will returns results like "amqp-client" or "amqpeter" or "cli-amqpbackend" * License Category: Filter components by various license risk categories including components with an "Undefined" license * Review status: By default, reviewed artifacts are not displayed. Use this toggle to display reviewed artifacts * Vulnerabilities: Filter by components that contain vulnerabilities.

# Module Tree Panel The Module Tree enables your team to navigate through files associate with each module. Selecting a node in the tree will cause the main panel to reload based on your context. Licenses, metrics and review status will also update based on components your tree context.

## Module Tree Panel Width The module Tree panel may also be adjusted by clicking and dragging the divider between the module tree panel and the main panel.

Use the pin to pin the current width of the panel

To create more space for the main panel, you can use the minimize areas to reduce the tree panel to it's minimum size.

While the panel is minimized, hovering over he module letters displays the full module name.

# Results Panel The component results view provides users with various ways to view components, meta-data and component risk. Two view options are available: **Card View**: Displays components in rectangular card format with available meta-data and license and vulnerability data. Cards can be filtered using the header panel filter mechanisms. Card view is the default view format for components. You can also switch to card view using the view options selector above header panel, shown in the image below. [Learn more here](/codecertify/components-tab/results-panel/card-view)

**Risk Graph View:** Threatrix risk graph enables users to consume various risk data is 2 dimensional graph. [Learn more here](/codecertify/components-tab/results-panel/risk-graph-view) # Card View Component scan results are grouped by the module and dependency manager from which they originated. The name of the module and path to the dependcy file are shown at the top of each grouping.

## Card Anatomy ### Component name & version The components name and version are derived from our knowledge base data as part of our comprehensive data ingestion process.

You can navigate to the component ecosystems provenance data by clicking on the provenance link shown below. Whenever possible, we make available the oriing or our data for the purposes of transparency and trust with our users. In the example below, the artifact absl-py originated from the Python ecosystem as evident by the pyton logo in the lower left corner of the image. Clicking the provenance icon will open a new tab to provenance of the exact version of this component. This allows users to quickly verify the integrity of our data, such as the Apache 2.0 license.

### Component License(s) All license data is available on the component card. If a single license is discovered, then the single license is shown directly on the component card, as shown below.

If multiple licenses are discovered, then you'll see "multiple" instead of the license name and will need to click on the word "multiple" to see the list of licenses, as shown below:

For both single and multiple licenses, a colored risk marker indicates the greatest license risk level. For example, if a component is licenses under MIT or Mozilla Public License 2.0, the risk marker color will be orange, to indicate the highest risk license. An example is shown below:

#### License Popup Menu The license popup menu is available by hover over the license name. The license menu provides four options: **View** The view menu option opens a dialog window that displays all available data for the license in question. An partial example is shown below. {% hint style="info" %} All license attributes including permissions, limitations and conditions are available in Threatrix policy engine and may be used to create polices to drive actions. {% endhint %}

**Provenance** In an effort to provide full transparency into the origins or artifact data, including licenses, we make every effort to verify the origins of our data and provide the provenance to the user. The provenance link will display the origin of the license, whether that's the asset text, license file or repository meta data, so that you can quickly make an informed decision about the license validity and efficacy. **Reject** Rejecting a license eliminates the license from both license metrics and reports. Rejecting an existing license is not required before adding another license. #### #### Adding a licenses ### Component Vulnerabilities Known vulnerabilities for components are displayed on the card and color coded by severity. The number of vulnerabilities for each severity is also provided. Shown below is an especially vulnerable version of tensorflow-cpu.

Clicking on individual metrics will produce a dialog with a complete list of all vulnerabilites in the metrics risk category.

From the above list, clicking on an individual vulnerability will provide the full details.

# Risk Graph View Clicking on the Risk graph icon will display the risk graph in reduced size format.

The risk graph may be maximized by by clicking the arrows in the top left corner of the graph.

# Audit History Audit history is helpful in determining the origin and timeline for changes made to artifacts. Changes to artifacts are automatically tracked by Threatrix platform and may be viewed by selecting Audit History from the 3 dot menu on the component card or menu.

Audit history tracks changes to artifacts including: * User who made the change * Change date * Review status changes * Developer actions or notes * License rejections, additions or modifications * Copyright additions or changes * Custom component changes * Auditor note additions or changes * Change comments

# Assets Tab # Custom Asset Matches ## What are Custom Asset Matches Custom Asset matches allow organizations to create and maintain a private knowledge base of asset matches that override the default values reported by Threatrix during scanning. ## How are Custom Asset Matches Used Custom Asset matches can be used to automatically associate Custom Asset Match data with assets that were unmatched during a scan. Custom Asset matches contain all of the necessary data that your team will need to account for any risk associated with the unmatched asset artifact, including licenses and copyrights. Custom Asset match data will be present on reports other risk management tools such Artifact Risk Graph(ARG). ## Important Notes Please read and understand some [Important Notes](https://docs.threatrix.io/codecertify/custom-asset-matches) regarding the creation, administration and application of Custom Components. # Adding Asset Match ## Eligibility Custom Asset matches may be added to both unmatched and matched asset artifacts. If you don't agree with an existing match, you can reject the match and add a custom Asset match using the process described below. ## Process to add custom Asset match Asset Custom matches must be added from the Assets screen in CodeCertify or Review screen in AICertfy. Use the 3-dot menu next to the Asset to which you'd like to add your custom match, as shown below {% hint style="info" %} More than one Asset match may be assigned to your source asset {% endhint %}

This will display the Add Custom Match dialog

You must enter the URL for the open source asset that contains the matching code

Then select the Check Asset button, in order to continue. This step verifies whether or not the asset is discovered in our Knowledge Base and auto-populates all of the necessary fields. Threatrix attempts to match the open source asset that you've provided with your source asset to calculate the Percent Match and Percent Copied values. In the case shown below, Threatrix could not find a matching body of code and shows a warning and requests that you complete the Percent Match and Percent Copied values. These values are NOT REQUIRED.

If you wish, you may override the license and/or copyright data provided by Threatrix. The License Search finds licenses in both Threatrix knowledge base and your Organizations private license knowledge base.

Once you're satisfied with the match data, click the Add button to associate the custom Asset match with your source file.

## Custom Asset Match List Your custom Asset matches knowledge base can be found in the Admin Settings under the Assets menu.

Clicking on a match displays the match details dialog

Custom Asset matches may be deleted by clicking the Delete icon next to each match.

## Important Notes * Deleting a custom Asset match does NOT remove existing matches from current scan results. A new scan is required for changes to be applied to matches. * Changes to knowledge base Asset matches will not be reflected in current scan results. This includes changes to licenses and copyrights. A new scan is required for changes to be applied to matches. * Changes to Asset artifacts with custom matches will only be reflected in the scan results and not applied to custom Assets in your organizations knowledge base. This includes changes to licenses and copyrights. # Project Dashboard Project dashboards are attached to entities and house the scan and historical data for a given project. Project dashboards include two sections; historical charts and scan results data. ### Charts Charts provide current quantitative metrics as well as historical metrics for the scans associated with the project. Scan dates are provided below the charts. * Vulnerabilities: Displays historical vulnerability metrics grouped by vulnerability severity. * Licenses: Displays historical license metrics grouped by license category. * Components: Displays historical metrics associated with the discovery of components in the project. * Asset composition: Displays historical breakdown of asset composition within your project. * Embedded: Your project file includes open source software. * Proprietary: Your project file is proprietary code. * Open Source: Your project file is open source. ![Project dashboard](/files/-MibIQq5ST2hX7DdsgEH) ### Scan Results Scan results data provides a history of summary data, with the most recent scan data highlighted and loaded for reference. Please see [Scan Results](/securecore/scan-results) for additional information on scan data and reviewing scan results. # ThreatScan ThreatScan provides a powerful, and simple way to scan a repository, components, or snippets of code to evaluate both vulnerability and license risk. ## Types of Scans ### Repository Scans {% hint style="warning" %} OAuth authentication is required for ThreatScan to grant the privileges necessary to scan your repositories directly from your SCM. {% endhint %} You can scan your public and private repositories using ThreatScan by [OAuth](/threat-center-1/creating-account/oauth-login) authentication through Github, Gitlab, or Bitbucket and then navigate to the ThreatScan dashboard. Once authenticated, the respective SCM repositories will be displayed on the ThreatScan dashboard. ### Scan your project using ThreatScan Once you've authenticated using OAuth, you will have access to your repositories from within our ThreatScan dashboard. To access the dashboard, from the top menu bar, click "ThreatScan." ![](/files/-MiSSUr7uJcLlXxaFAtt) Your repositories will be available for scanning immediately, as shown in the screenshot below. ![](/files/-MiST0rYd-uWAH9nRg7x) # Scan Results This is a handy guide to help you understand the scan results of your project and take the necessary actions to remediate security and licenses risks. ### Origin Of Scan Results Scan results are the byproduct of scans that occur either from with the dashboard, using [ThreatScan](/securecore/threatscan), or from within your integrated [DevOps](/resources/dictionary#devops) environment, typically within your build servers. ### Locating Scan Results Scan results are always associated with the project that was scanned to produce the results. We use various methods to determine the project name, in the following order: * [Dependency manager](/resources/dictionary#dependency-manager) project name (varies by dependency manager). * The folder name of the root of the project directory. * As a last resort, we will create a [GUID](/resources/dictionary#guid). * A random character is chosen from Star Wars or Star Trek. (we're kidding, but this would be fun!) All projects are attached to an [Entity](/resources/dictionary#entity). When you log in, you are automatically dropped into your default business unity entity. From here, you can access all of the projects you are authorized to view, as shown below. You can return to your home entity by clicking "My Business Unit" on the top menu bar. From within your home entity, projects and their associated scan results are available under the `Projects` tab, as shown below (with charts minimized). ![](/files/-MiTz9CGYmVBj2JhedJQ) ### Entity Project Summary Data Each list of projects includes its associated summary data to ascertain the risk factors for that project quickly. * **Vulnerability Risk**: Quantitative vulnerability metrics by vulnerability severity. * **License Risk**: Quantitative breakdown of licenses by category and risk. * **Asset Composition**: Quantitative data showing the composition of your project broken into three categories: * **Embedded**: Your proprietary source code contains some open source. * **Open Source**: You have open source files in your project. * **Unique**: A project file that is 100% proprietary source code with no open source. ![](/files/-MiU-2poiWDJ7GQRCJnv) ### Project Dashboard The project dashboard is segmented into two mains areas; chart summary data over time and scan detail data for specific scans. ![](/files/-MiUH3hLQsuxqgl0Wg56) ### Scans Tab The most recent scan results are displayed by default, but the user can select any scan results for one year. Selecting a scan will automatically reload the scan data to make it available from within the tabbed panes and reload the quantitative data within each tab. ![](/files/-MiUHsNQ7pplveLv9pDm) **Column Descriptions** * **ID**: The abbreviated internal scanID of the scan. It may be copied to your clipboard but clicking on the ID value. * **Commit** The version commit hash provided by your SCM for this scan. * **Branch name**: Name of the branch that was scanned. * **Tag**: A tag value that was provided with the scan. * **Created**: The date that the scan was created (the project scan timestamp) as MONTH/DAY HH: MM. * **Vulnerabilities**: Quantitative values of scan vulnerabilities by severity (mix of CVSS2 & CVSS3). * **Licenses**: Quantitative license values of the scan by license category. * **Asset Composition**: Quantitative data of scan showing the composition of that scan version broken into three categories; * **Embedded**: Your proprietary source code contains some open source. * **Open Source**: 100% open source file in your project. * **Unique**: A project file that is 100% proprietary source code with no open source. ![Scan History (click to enlarge)](/files/-MiUNgzAY8xXDYbl_Z-c) ### Vulnerabilities Tab All scan vulnerability data is available within the vulnerabilities tab. The table format allows for an easy and quick review of a large volume of data. **Column Descriptions** * **Vulnerability**: The unique ID of the vulnerability provided by the source of the vulnerability data or a proprietary value provided by Threatrix. * **Component**: The name of the component that contains the vulnerability. * **Group**: The group value of the component if provided by the [dependency manager](/resources/dictionary#dependency-manager). * **Version**: The version of the component that you're project is using. * **CWE:** The common weakness and enumeration w/description from the origin vulnerability database or provided by Threatrix. * **Severity**: The severity assigned to the vulnerability. * **CVSS2**: The CVSS2 score assigned to the vulnerability. * **CVSS3**: The CVSS3 score assigned to the vulnerability. Please note: columns with a filter header allow for filtering on column values. ![Vulnerabilities Tab (click to enlarge)](/files/-MiUPQj6NzEh4HFrtXV8) ### Components Tab The components tab provides a complete list of all [discovered](/resources/dictionary#discovered) and [declared](/resources/dictionary#declared) components for the selected scan version. For each component, a list of both licenses and vulnerabilities is provided. For vulnerabilities that include a suggested fix, a "Fix" button will be displayed, allowing users to remediate those vulnerabilities easily. Clicking Fix provides two possible options: * Upgrade to latest secure version: Modifies underlying dependency manager configuration to upgrade the chosen component to the latest (newest) [secure version](/resources/dictionary#secure-version) and creates a pull/merge request for that change. * Upgrade to next [secure version](/resources/dictionary#secure-version): Modifies underlying dependency manager configuration to upgrade the chosen component to the next [secure version](/resources/dictionary#secure-version) and creates a pull/merge request for that change. **Column Descriptions** * **Name**: The name of the component that contains the vulnerability. * **Group**: The group value of the component is provided by the [dependency manager](/resources/dictionary#dependency-manager). * **Version**: The version of the component that you're project is using. * **Internal**: If this component is external or marked as internal. * **Location**: The location of where we found this component. * DEPENDENCY FILE: A component declared by your dependency manager. * DRIVE: A component discovered on the drive (e.g., jar, war, exe, bin, .js, .py, etc.). * STATIC\_REF: Discovered as a [static reference](/resources/dictionary#static-reference) in an HTML or other supporting file. * **Discovery**: The method of discovery for this component. * DECLARED: The component was declared within a dependency manager. * DISCOVERED: The component was discovered on the drive as a static reference or embedded in your proprietary software. * **Licenses**: The licenses associated with this component. Threatrix includes all discovered licenses, including those. ![Components Tab (click to enlarge)](/files/-MiUSUOdKieotSjVFRem) ### Licenses Tab Licenses, both [discovered](/resources/dictionary#entity) and [declared](/resources/dictionary#declared), are presented in list format for each consumption. **Column Descriptions** * **Name**: The name of the license. * **SPDX**: The SPDX identifier for the license, if available. * **Threat category**: The category of the license color-coded by its potential threat risk to your organization. License categories are as follows: * UNDEFINED * PROPRIETARY\_FREE * PUBLIC\_DOMAIN * PROPRIETARY * PERMISSIVE * COPYLEFT * COPYLEFT\_WEAK * COPYLEFT\_LIMITED * COPYLEFT\_PARTIAL * COPYLEFT\_STRONG * **Style**: The [style of the license](/resources/licenses#styles) * **Discovery**: The method of discovery for this license * DECLARED: The license was declared within a dependency manager, in a LICENSE file, or as the license attached to the source of the distribution repository. * DISCOVERED: The license was discovered in the source code or as part of an [embedded asset](/resources/dictionary#embedded-asset) (open source snippet). * **Origin:** Discloses the origin for the method of discovery * COMPONENT * REPOSITORY * REPOSITORY\_META * REPOSITORY\_LICENSE * ASSET * **OSI Approved**: The license has been approved by the Open Source Initiative. * **FSF Libre**: The license has been approved by the Free Software Foundation You can find more information on licenses and license metadata within our [Resources](/resources/licenses) area. ![License Tab (click to enlarge)](/files/-MiXM-RdohBWsr1y89k3) ### Assets Assets represent all of the files that we discovered during our scan. They're structured and navigable similar to Github, allowing you and your team to be confident with the results. We have located all of your source code and, more importantly, all of your open source. This allows you to understand if and how it was processed. **Column Descriptions** * **Name**: The name of the asset. * Asset names with format $NAME#$NAME are those from which open source was referenced within the file. e.g.`account.html#jquery.js` indicates that jquery was referenced inside this HTML file. * **File size:** The size of your project asset. * **Status:** The processing status of the asset. Potential status values include: * IGNORED\_SIZE\_SMALL: Size < 256b * IGNORED\_SIZE\_LARGE: Size > 100MB * IGNORED\_SIZE\_EMPTY: Size = 0 * IGNORED\_TYPE\_UNSUPPORTED: Indicates an unsupported file type. * IGNORED\_TYPE\_DIRECTORY: A directory. * ACCEPTED: Accepted for processing. * **Embedded / Total %**: Indicates the count of embedded open source matches and the total percentage of your asset that consists of open source. Our algorithm does not provide an exact percentage value. The actual percentage could vary up to 10%. The larger the overall match, the greater the accuracy of the match estimate. This column includes a header filter that allows the filtering of assets to show all of the embedded asset matches. * **Attribution:** Indicates the status of [license attribution](/resources/licenses#attribution) of the source file. * **Match Type:** Indicates the amount of open source, if any, in your project asset. Possible values are: * PROPRIETARY: A project asset with < .01% open source. * PROPRIETARY/OPEN SOURCE: A project asset with between .01% and 50% open source. * OPEN SOURCE/PROPRIETARY: A project asset with between 51% and 99.99% open source. * OPEN SOURCE: A project asset that is 100% open source. * OPEN SOURCE COMPONENT: A project asset that is categorized as an open source component. ![Assets Tab (click to enlarge)](/files/-MiYLu-ptG3zTz_916EU) Assets that include embedded open source allow you to click through to see the details of the open source matches, view the match side-by-side in our SIMM tool, and automatically attribute your source file with the necessary licenses. Shown below is a screenshot of the embedded asset match details screen. **Column Descriptions** * **Name**: The name of the matching open source file in the source repository is shown in the repository column. * **Repository**: The repository type, owner, and name of the repository for this match. This field is clickable and will take you to the repository. * **Percent Match**: The estimated percentage of your proprietary asset consists of the open source for this match. * **Versions**: The version range for which this exact match correlates. Files change over time, and these are the ranges that reflect this exact match. It's important to know the version ranges because licenses are associated with the released versions of the open source components. Clicking this column record will provide the complete details for each release, include release dates. * **Licenses**: All of the licenses associated with the discovered version ranges of this match. Clicking this column record will provide details of the license associated with each matched version of the component. * **SIMM:** Threatrix similarity tool allows you to view the similarities between two assets. ![](/files/-MiYrBf-iq_3UjNpZ6AH) # Threat Agent Overview Threat Agent is a lightweight CLI scanning agent which will effectuate scans during builds for automated scanning or ad-hoc scans from a desktop, server, or container. # Threat Agent - Installation & Scanning Threatrix Threat Agent is a CLI scanning agent intended for use in situations where you don't want to scan directly from Github, Gitlab, or other source control management platforms. ## Getting Ready to Scan Before running a scan with Threat Agent you should create an API key and collect your Organization ID and Entity ID from your profile screen as shown below. These can be set as environment variables or passed directly as arguments to Threat Agent during a scan.

## Threat Agent Deployment Types Threat Agent can be deployed in two ways. 1. **Download and install directly on host -** This requires that you have all your dependency managers installed on you host as they will be required by Threatrix to perform a scan 2. **Docker Deployment -** If you're familiar with Docker and your deployment environment supports it, this is the easiest way to get up and running with our Threat Agent. ## Host install and scanning ### 1. Download Threat Agent CLI ``` curl -LJO https://github.com/threatrix/threat-matrix/releases/download/agent-release-latest/threat-agent-latest.jar ``` ### 2. Run Threat Agent CLI ``` java -jar threat-agent-latest.jar --oid={ORGID} --eid={ENTITYID} --api-key={AIPKEY} $PATH_TO_PROJECT ``` ## Docker Scanning ``` sudo docker run --rm --name threatrix-threat-agent -v $(pwd):/app threatrix/threat-agent \ --oid={ORGID} \ --eid={ENTITYID} \ --api-key={API_KEY} $PATH_TO_PROJECT ``` ## Command line options

	Type	Required
Argument/Flag	Type		Description
--app-name	argument	Optional	Set or override the default project name
--api-key	argument	Required	API Key from your user profile
--api-url	argument	Optional	Threatrix API url (no need to change unless you have a self-hosted Threatrix server)
--oid	argument	Required	OrganizationID from user profile
--eid	argument	Required	EntityID from user profile
--scpId	argument	Optional	Existing AICertify or CodeCertify projectId
--repo-owner	argument	Optional	Repository Owner
--repo-name	argument	Optional	Repository Name
--branch	argument	Optional	Current Branch
--scm	argument	Optional	Indicates the sourced control management system to which the build is attached. Possible options are GITHUB GITLAB BITBUCKET
--scm-access-token	argument	Optional	The token required to create pull/merge request scan reports.
--verbose	flag	Optional	Activate debugging
--progress	flag	Optional	Show progress during scan

# Scan Summary Reports Scan summary reports are integrated directly into a pull/merge request and enable your team to quickly assess the risk and policy violations associated with the most recent build integrated scan. ### Configuration An SCM access token is necessary to enable the creation of comments against pull requests. A personal access token may be used for this purpose, but we highly recommend that a service user be created and managed by the administrator of your SCM. A PAT for the service user requires only `repo` rights to the repositories on which PR comments will be created. The new access token will need to be added as a secure environment variable build system as `SCM_AUTH_TOKEN` {% hint style="info" %} Scans must be launched as a result of a git pull/merge request originating from your SCM. {% endhint %} Summary reports are created as a comment attached to your pull/merge request. They include quantitative summary data for Vulnerabilities, Licenses, Asset composition, and associated policy violations. Users may click the project name to be redirected directly to the project page to review the full scan results.

See [Installation & Configuration](/threat-agent/install-config) for more details. # Resolving Errors ## Resolving "PKIX path building failed" and "unable to find valid certification path to requested target" This error is most commonly experienced on Windows operating systems as a result of the default keystore installed with Java. ### Export SSL certificate from browser Open your browser and navigate to or your local Hybrid threatrix deployment server. Follow the instructions below to export the SSL certificate from your browser: #### **chrome** Click on site icon left to address in address bar, select "Certificate" -> "Details" -> "Export" and save in format "Der-encoded binary, single certificate, save as app.threatrix.io.crt". #### **firefox** Click on HTTPS certificate chain (the lock icon right next to URL address). Click "more info" > "security" > "show certificate" > "details" > "export..". Saver as app.threatrix.io.crt #### edge Click on site icon left to address in address bar, select "Connect is secure" -> "Show Certificate icon(top right)" -> "Details -> "Export" and save as app.threatrix.io.crt. ### Import SSL certificate into Java keystore as trusted certificate Locate your Java cacerts file, which is installed with Java, typically under $JAVA\_HOME\lib\security\cacerts If a password is required, the default password for java keystores is "chnageit". use Java keytool to import it into your Java keystore ``` keytool -import -trustcacerts -alias threatrix -file app.threatrix.io.crt -keystore cacerts ``` # Scanning Container Images ## Syntax for scanning a public container image ``` java -jar threat-agent-latest.jar useAgentV2=false --oid={ORG_ID} --eid={ENTITY_ID} --apikey={API_KEY} image:docker.io/nginx:latest ``` ## Syntax for scanning a private container image It is recommended to setup a service account in your container registry and create a service token for your service account to be used in the Threat Agent. ```bash java -jar agent.jar useAgentV2=false --oid={ORG_ID} --eid={ENTITY_ID} --apikey={API_KEY} --registry-login={LOGIN} --registry-password={ACCESS_TOKEN} image:docker.io/threatrix/threat-agent:latest ``` # Dependency Managers A list of supported dependency managers and their associated documentation. Threatrix Platform supports the fallowing Dependency Managers: | Dependency Manager(s) | Language | | --------------------- | --------------------- | | Maven | Java/Kotlin | | Gradle | Java/Kotlin | | NPM | Typescript/Javascript | | PIP/pipenv | Python | | Poetry | Python | | Nuget | C# | | GoMod | Go | | CocoaPods | Objective-C/Swift | | LuaRocks | Lua | | Conan | C/C++, Various | | Rubygems | Ruby | | Mix/Hex | Elixir (few Erlang) | | Rebar3 | Erlang (few Elixir) | | Cargo | Rust | | yarn | Javascript/NodeJS | | PHP Composer | PHP | | RENV | R | # RENV This is the documentation for the RENV dependency manager for R language ## Dependencies Threatrix RENV support requires RENV to be installed on the machine on which the Threat Agent is running. If not already installed, you may install RENV with the following command: `R -e "install.packages(\"renv\")"` ## Setup Threatrix RENV support requires an renv.lock file to be present in order to create the bill of materials. If one is not present, it may be created using the following instructions. Once created, it should be committed and managed with your other repository code.\ \ Create a file named `create-renv-lock` in the same directory as the `DESCRIPTION` file and add the following contents: ``` # R script for RENV dependency manager that creates package lock file dependency.errors <- getOption("renv.config.dependency.errors") install.transactional <- getOption("renv.config.install.transactional") snapshot.validate <- getOption("renv.config.snapshot.validate") options(renv.config.dependency.errors = "ignore") options(renv.config.install.transactional = FALSE) options(renv.config.snapshot.validate = FALSE) renv::init( settings = list(snapshot.type = "explicit") ) renv::snapshot(force=TRUE, type="explicit") options(renv.config.dependency.errors = dependency.errors) options(renv.config.install.transactional = install.transactional) options(renv.config.snapshot.validate = snapshot.validate) ``` From the same directory with the create-renv-lock, run:\ `R --vanilla -s -q -f ./create-renv-lock` An `renv.lock` file should be created and present in the same directory as your `DESCRIPTION` file. The `renv.lock` should be updated whenever your `DESCRIPTION` file is updated and committed to your source repo so that it's available with each scan. ## Usage No additional steps are necessary. Simply run Threatrix Threat Agent and it will create the associated bill of materials using RENV. ## Errors and Runtime Issues ### Timeouts During Executing If you're seeing timeouts while running the Threat Agent in an environment with RENV, but without the required renv.lock file, we will attempt to create the renv.lock, which may lead to timeouts after 15 minutes. Best practice is to ensure that your team creates the necessary renv.lock and commits it to your repo so that our agent does not have to recreate with every scan. # Build Integrations Build integrations enable the automated scanning of your projects for continuous security and compliance across all your projects and products. ## Currently Supported Integrations * Azure DevOps * Jenkins Pipeline * Bitbucket Pipeline * Circle CI * GitHub Actions * Gitlab Pipeline ## Build Integration Steps Threatrix [Threat Agent](/threat-agent/threat-agent-1) runs scans from within your build environment, allowing for automated and continuous open source security and license compliance data to be sent to your team. As a build step, scans run during a build and are typically kicked off during a pull request. Integrated scans enable your development to spot security problems, in your open source, before merging their changes into your main branch. [Scan summary reports](/threat-agent/scan-summary-reports) can be generated to annotate your pull request making it fast and easy for developers to find and fix vulnerabilities and license violations. **Just a few simple steps are required to get you up and running.** 1. Collect the information required to configure your build environment. 2. Configure your build server with the environment variables. 3. Add a build step to download Threat Agent and execute a scan. ### Environment Variables Whlle these values can be passed directly to the agent on the command line, it's often more security and helpful to implement them as environment variables within your build server. * THREATRIX\_OID \[REQUIRED]: The organization ID - Found in admin and user profile. * THREATRIX\_EID \[REQUIRED]: The entity ID for which scan results will be associated. This must be an entity for the user associated with the API\_TOKEN to have rights. * THREATRIX\_API\_KEY \[REQUIRED] - The access key used for the scan. Found in the admin or user profile ### Threat Agent Scan Options Our Threat Agent requires minimal configuration as it can detect it's environment and self configure based on that context. However, several [command line options](/threat-agent/install-config#scan-flags) and scan are available. ### Build Server Configuration Please see the respective build server documentation. # AWS CodeBuild ### Common Build Integration Documentation This documentation is specific to AWS CodeBuild. [Common build server](/integrations/build-integrations) documentation should be reviewed before proceeding further. ### Environment Variables Before continuing, you'll need to collect the following values from your Threatrix account. Please refer to [Common build server](/integrations/build-integrations) documentation for details on where to find these values. Environment variable values can be found in your [user profile](/threat-center-1/user-profile). * THREATRIX\_OID - Your organization ID. * THREATRIX\_EID - Your entityID * THREATRIX\_API\_KEY - Service/API key. ### Install ThreatAgent into AWS CodeBuild pipeline ### Add CLI Threat Agent Edit your existing *buildspec.yml* file to add the following two commands to download the agent and run the scan during your build. The oid, eid and api-key may be setup as environment variables or the values may just be pas as arguments directly to the agent. Simple replace the curly brace holders with the associated values. ``` phases: pre_build: commands: - curl -LJO https://github.com/threatrix/threat-matrix/releases/download/agent-release-latest/threat-agent-latest.jar - java -jar threat-agent-latest.jar --oid={THREATRIX_OID} --eid={THREATRIX_EID} --api-key={THREATRIX_API_KEY} . ``` # Azure DevOps ### Set up User Variables **Within Threatrix Threat Center** * Grab your OrgId and EntityId credentials from your profile

* Create and grab your API Key from your profile or admin dashboard at Admin -> Integration -> Service keys. When creating the Service Key, be sure to choose "Super Admin" for the role. Choosing permissions is unecessary.

**Within Azure DevOps** * Navigate to Pipelines -> Library * Click \`+Variable Group\` to add a new Variable Group * Create a new Variable * Set "Threatrix" for Variable group name * Add the following Variable Names with values * THREATRIX\_API\_KEY: Your API Key from your profile or admin dashboard * THREATRIX\_OID: Your organization ID from your profile * THREATRIX\_EID: Your entity ID from your profile * \[OPTIONAL] Select Lock icon for each to convert to Secret variable * From top menu, click "Save".\
![](/files/dajyi7RaEkJ89R3z4e81) ### Variables Permissions During your next build, you may see the following message requesting permissions to access your newly created Variable Group. Select "Permit" in order to allow the pipeline access to Threatrix variables necessary to perform the scan. ![](/files/sNN01bEB8Vp7vmt7pG6O) ### Installing Threat Agent Threatrix Threat Agent requires that Java 11+ be pre-installed on the host machine. **Download and run the latest ThreatAgent in your pipeline** Add the following step to your azure-pipelines.yml file ``` - script: | curl -LJO https://github.com/threatrix/threat-matrix/releases/download/agent-release-latest/threat-agent-latest.jar java -jar threat-agent-latest.jar ./ ``` # Bitbucket Pipeline ### Common Build Integration Documentation This documentation is specific to Gitlab. [Common build server](/integrations/build-integrations) documentation should be reviewed before proceeding further. ### Environment Variables Environment variable values can be found in your [user profile](/threat-center-1/user-profile). * THREATRIX\_OID - Your organization ID. * THREATRIX\_EID - Your entityID (if you wish to override your default). * THREATRIX\_API\_KEY - Personal or organization API key. ### Install Environment Variables {% hint style="warning" %} This step may require administrative privileges within Gitlab {% endhint %} 1. From your avatar in the bottom left, select a workspace. 2. Select **Settings** on the left navigation sidebar to open your Workspace settings. 3. In the menu on the left, go to **Pipelines** > **Workspace variables**. * Workspaces variables can be overridden by repository variables. * Workspace variables can be accessed by all users with the *write* permission for any repository (private or public) that belongs to the team or account. * You must be an administrator of a workspace or a repository to manage variables respectively. Click "Add Variable" to add THREATRIX\_OID and THREATRIX\_API\_KEY and optionally, a THREATRIX\_EID for which the API key has permissions to create projects. ![](/files/QqeiqcgbQPyV7QZwoSDq) ### Add ThreatAgent to your build step You have two options to add Threatrix TheatAgent to your build step. 1\) Using our ThreatAgent CLI directly. This is the best option if you already have Java installed on your build server or you have a complex build environment 2\) Use our Dockerized agent. ### Option 1: Add Docker Threat Agent Step to Build In Bitbucket, in your repository you wish you run your scan, create a bitbucket-pipelines.yml `file` and add the following contents. ``` - step: name: ThreatScan script: - curl -LJO https://github.com/threatrix/threat-matrix/releases/download/agent-release-latest/threat-agent-v2.1.2.jar - java -jar threat-agent-v2.1.2.jar ``` ### Option 2: Add Docker Threat Agent Step to Build In Bitbucket, in your repository you wish you run your scan, create a bitbucket-pipelines.yml `file` and add the following contents. ``` - step: caches: - docker name: ThreatScan script: - printenv > host.env - docker run -v $(pwd):/app --env-file=host.env threatrix/threat-agent ./ ``` # CircleCI ### Common Build Integration Documentation This documentation is specific to CircleCI. [Common build server](/integrations/build-integrations) documentation should be reviewed before proceeding further. ### Environment Variables Environment variable values can be found in your [user profile](/threat-center-1/user-profile). * THREATRIX\_OID - Your organization ID. * THREATRIX\_EID - Your entityID (if you wish to override your default). * THREATRIX\_API\_KEY - Personal or organization API key. ### Install Environment Variables {% hint style="warning" %} This step may require administrative privileges within CircleCI {% endhint %} From within CircleCI navigate to "Organization Settings->Contexts"

Click the Create Context button and create a new Context named "Threatrix"

After creating the context, click on the name to add environment variables to the context.

From within the Add Environment Variable dialog, enter the necessary variable values. * THREATRIX\_OID - Your organization ID. * THREATRIX\_EID - Your entityID (if you wish to override your default). * THREATRIX\_API\_KEY - Personal or organization API key. ![](/files/-Mj1ivZuQ0d6E6m2aF26) ## Add the Threatrix Agent to your build server. First,Add threatrix context to your job

### Option 1: Add CLI Threat Agent From within your SCM repository, add the following snippet to your .circleci/config.yml file or download a full example here: {% file src="/files/xstHcHxOz27f5yUp8NBW" %} config.yml {% endfile %} ```yaml # Execute Threat Scan - run: name: Install Threatrix ThreatAgent & Scan command: | curl -LJO https://github.com/threatrix/threat-matrix/releases/download/agent-release-latest/threat-agent-latest.jar java -jar /tmp/threatagent.jar --progress ``` ### Option 2: Add Docker Threat Agent Step to your build {% hint style="warning" %} **Prerequisite: In order to use our Docker image, your build executor must be of type `machine` otherwise, we'll be unable to create the necessary Docker volume** {% endhint %}

Add the following code snippet as a step to your existing build job. The threatrix scan agent should run either before or in parallel with your build job. ``` - run: name: Threatrix Scan command: | printenv > host.env docker run -v $(pwd):/app --env-file=host.env threatrix/threat-agent ./ ``` # GitHub Action ### Common Build Integration Documentation This documentation is specific to GitHub. [Common build server](/integrations/build-integrations) documentation should be reviewed before proceeding further. ### Environment Variables Environment variable values can be found in your [user profile](/threat-center-1/user-profile). * THREATRIX\_OID - Your organization ID. * THREATRIX\_EID - Your entityID (if you wish to override your default). * THREATRIX\_API\_KEY - Personal or organization API key. ### Install Environment Variables as Secrets {% hint style="warning" %} This step may require administrative privileges within GitHub {% endhint %} 1. From within Github, navigate to Organization -> Settings -> Secrest and variables 2. Select "Actions" from the menu 3. Click New organization secret button 4. Set secret name as shown above in Environment Variables 5. From the Repository access drop down, select either "Private Repositories" or "Selected repositories" 6. Click "Add secret"

### Add Threat Agent to your GitHub Action script as follows: ``` on: pull_request: types: - 'opened' - 'reopened' workflow_dispatch: jobs: execute-scan-workflow: uses: threatrix/threat-agent-scan/.github/workflows/scan-repo-reusable.yaml@master with: app-name: YOUR_PROJECT_NAME trx-host: https://app.threatrix.io secrets: TOKEN: ${{ secrets.GITHUB_TOKEN }} THREATRIX_EID: ${{ secrets.THREATRIX_EID }} THREATRIX_OID: ${{ secrets.THREATRIX_OID }} THREATRIX_SERVER_API_KEY: ${{ secrets.THREATRIX_API_KEY }} ``` # GitLab Pipeline ### Common Build Integration Documentation This documentation is specific to Gitlab. [Common build server](/integrations/build-integrations) documentation should be reviewed before proceeding further. ### Environment Variables Environment variable values can be found in your [user profile](/threat-center-1/user-profile). * THREATRIX\_OID - Your organization ID. * THREATRIX\_EID - Your entityID (if you wish to override your default). * THREATRIX\_API\_KEY - Personal or organization API key. ### Install Environment Variables {% hint style="warning" %} This step may require administrative privileges within Gitlab {% endhint %} From within Gitlab, navigate to Settings -> CI/CD -> Variables, as shown below. ![](/files/-MbtEsIU_FARUnsL8oY5) Click "Add Variable" to add THREATRIX\_OID and THREATRIX\_API\_KEY and optionally, a THREATRIX\_EID for which the API key has permissions to create projects. ### Option 1: Add CLI Threat Agent ``` threatrix-scan: script: - curl -LJO https://github.com/threatrix/threat-agent-dist/releases/download/latest/threat-agent.jar - java -jar threat-agent.jar . only: - merge_requests ``` ### Option 2: Add Docker Threat Agent Step to Build In Gitlab, in the repository you wish you run your scan, create a `.gitlab-ci.yml file` and add the following contents. {% hint style="warning" %} This option may not work for Gitlab On-Prem deployments. Please use Option 1 for Gitlab On-Prem. {% endhint %} ``` threatrix-scan: image: gitlab/dind script: - printenv > host.env - docker run -v $(pwd):/app --env-file=host.env threatrix/threat-agent ./ only: - merge_requests ``` # Jenkins Pipeline ### Install Docker and Docker Pipeline plugins(if not already installed) * Navigate to Manage Jenkins * Manage Plugins * Select the "Installed" tab and enter "docker" in the filter box * From the results, you should find Docker Plugin and Docker Pipeline as shown below ![](/files/AF8clDyMkuY88MkqpuYE) ### Install Environment Variables * Grab your orgId and entityId credentials from your profile * Create and copy an API Key from your profile or Service Key from your admin dashboard (Admin -> Integration -> Service Keys) * Go to "Manage Jenkins" > "Manage Credentials" * Choose a Store * Choose a Domain * Go to "Add Credentials" * Select "SecretToken" * Configure the following Credentials * THREATRIX\_OID (orgId from profile) * THREATRIX\_EID (one entityID from your list of Entities) * THREATRIX\_API\_KEY(your personal API Key from profile or Service Key from Admin) ![](/files/YIadY2JwcN3zmYDBKHN9) ### Install Threat Agent in Pipeline * Navigate to the pipeline into which you wish to install Threatrix scan agent * Click configure and navigate to the bottom of page to edit "Pipeline" script * After the stage(s) where you pull your project(s) into the workspace on the build server, add the following stage snippet to your Pipeline script ``` stage('Threatrix Scan') { environment { THREATRIX_OID = credentials('THREATRIX_OID') THREATRIX_EID = credentials('THREATRIX_EID') THREATRIX_API_KEY = credentials('THREATRIX_API_KEY') } steps { script { sh 'curl -LJO https://github.com/threatrix/threat-matrix/releases/download/agent-release-latest/threat-agent-latest.jar > /tmp/threatagent.jar' sh 'java -jar threatagent.jar --oid=${THREATRIX_OID} --eid=${THREATRIX_EID} --api-key=${THREATRIX_API_KEY} ./' } } } } ``` ### Install Threatrix Docker in Pipeline * Navigate to the pipeline into which you wish to install Threatrix scan agent * Click configure and navigate to the bottom of page to edit "Pipeline" script * After the stage(s) where you pull your project(s) into the workspace on the build server, add the following stage snippet to your Pipeline script ``` stage('Threatrix Scan') { environment { THREATRIX_OID = credentials('THREATRIX_OID') THREATRIX_EID = credentials('THREATRIX_EID') THREATRIX_API_KEY = credentials('THREATRIX_API_KEY') } steps { script { sh 'sudo docker pull threatrix/threat-agent' sh 'sudo docker run --rm --name threatrix-threat-agent -v $(pwd):/app threatrix/threat-agent --oid=${THREATRIX_OID} --eid=${THREATRIX_EID} --api-key=${THREATRIX_API_KEY} ./' } } } } ``` # SCM Integrations Integrate with your cloud and on premise SCM's to perform OAuth authentication for users and run scans directly from Threat Center # GitLab ## Prepare for SCM Integration Setup * Within Threat Center, navigate to Admin-> Settings->Integrations->SCM Integrations. * Take note of your Redirect URL as you'll need it in the next step. ## Create Instance or Group GitLab OAuth Application Login to GitLab with a user that has permission to create an application 1. Login to GitLab with a user that has permission to create an application 1. This should be a service account. 2. Navigate to the group for which you wish to add the application 3. On the left menu, select Select Settings -> Applications 4. Click "Add new application" 5. Enter Name "Threatrix" 6. Enter the `Redirect URIfrom the Threatrix dashboard` 7. Select the following permissons: * api (Access the authenticated user's API) * read\_user (Read the authenticated user's personal information) * read\_repository (Allows read-only access to the repository) * write\_repository (Allows read-write access to the repository) 8. Click "Save application" Copy your application ID and Secret as you'll need them for the next step.

## Complete SCM Integration In Threat Center, SCM Integration, complete the following fields * Name: Use a unique name that employees will recognize, like your team, group or division. If necessary, add the SCM type if there are more than one in the same group. * Provider Type: Select GITLAB from the * Base URL: This is the URL of your SCM server * Token URL: The Token URL of your server * Authorization URL: The authorization URL of your server * Client ID / Application ID: This is the Application ID or Client ID provided to you when you created your application in your SCM * Client Secret / Secret: This is the secret provided to you when you created your application in your SCM.

# Bitbucket ## Prepare for SCM Integration Setup * Within Threat Center, navigate to Admin-> Settings->Integrations->SCM Integrations. * Take note of your Redirect URL as you'll need it in the next step. ## Create Group Bitbucket OAuth Application Login to GitLab with a user that has permission to create an application * Login to your Atlassian or Bitbucket account with a user who has permission to create an application * If necessary, switch to Bitbucket from the top left Atlassian menu. * Select the **Settings** cog on the top navigation bar. * Select **Workspace settings** under **Bitbucket Administration** from the **Settings** dropdown menu.\ If you're giving access to a workspace, make sure you have administrative access. * Select **OAuth consumers** under **Apps and Features** on the left navigation sidebar. * Select **Add consumer**. The **Add OAuth consumer** page appears. * Enter Name "Threatrix" * Enter the `Redirect URIfrom the Threatrix dashboard` * Select permissions as shown below * ```

``` * Click "Save" Copy your application ID and Secret as you'll need them for the next step.

## Complete SCM Integration In Threat Center, SCM Integration, complete the following fields * Name: Use a unique name that employees will recognize, like your team, group or division. If necessary, add the SCM type if there are more than one in the same group. * Provider Type: Select BITBUCKET from the * Base URL: This is the URL of your SCM server * Token URL: The Token URL of your server * Authorization URL: The authorization URL of your server * Client ID / Application ID: This is the Application ID or Client ID provided to you when you created your application in your SCM * Client Secret / Secret: This is the secret provided to you when you created your application in your SCM.

# Issue Management Integration with issue management systems. The Threatrix Platform supports integration with the following issue management systems. These integrations can be configured under Admin > Settings > Integration. * Jira * GitHub Issues # Jira ## Getting Started You'll need the following data to being your integration with Jira * Project URL * Project Key * Issue Type * login/email for account * Jira API Token ## Project URL You can get your project URL from the browswer by navigating to your project and copying the portion of the URL that reflects the only the domain name for your Jira account, as shown below:

## Project Key Your project key can be retrieved from your project settings at under your details tab:

## Issue Type Issue types are found in Jira under you project settings Issue Types menu. Default Jira issues types are: Epic, Task and Subtask

## Create Jira Token The first step is to create a Jira token that can be used with your Threatrix integraition. We suggest creating a service accont that can be used for this purpose, but any user account, with appropriate privledges, can be used for this purpose. 1. Login to Jira and Navigate to \`Atlassian Account -> Security -> Create API Tokens\` or just use this link.\ [https://id.atlassian.com/manage/api-tokens]() 2. Click "Create New Token" button and give it a name and expiration date. Be aware that your Threatrix integration will stop functioning after the token expires. 3. Be sure to Copy the token and store it somewhere safe. \\ ## Setup Integration Now that we have all of the necessary data to contiguration the integration, let's get started. 1. Login to Threatrix Threat Center and navigate to Admin -> Settings -> Integration -> Jira Integration 2. Enter the values collected in the previous steps 3. Click "Save" to commit the changes.

And, now you're ready to create tickets from Threat Center! ## Creating Jira Tickets Jira tickets can be created in three ways: 1. Directly from the Vulnerability details screen. Once the ticket is created, a link to the Ticket will be added to the license details screen.

2. Directly from license details screen:\

\ Once the ticket is created, a link to the Ticket will be added to the license details screen.

3. Automatically from within polices. \ From withing policies, edit the policy for which you'd like to create a Jira ticket. Edit the policy and Navigate to the actions tab. Select "Add new action" and then select "Issue" from the Action drop down and Type Jira. You may also add notes to the policy which will flow through to the Jira ticket to provide guidance to your development team.

# Notifications Push notification support for various channels. The Threatrix Platform supports integration with the following Notification Channels. These can be configured under Admin > Settings. * Email * SLACK Channels # Policy Overview A handy guide for Threatrix policy management system ### What Are Policies? Threatrix policies define the rules by which events occur within the Threatrix ecosystem. They enable your team to define, disseminate and enforce the governing guidelines that reduce your security, license, and supply chain risk in your organization. ### Policy Composition Policies are composed of 3 components: 1. Policy metadata: title, category, and description data. 2. Policy conditions: Conditions on which to match against the policy. 3. Policy actions: The resulting pre-determined process that will be executed as a result of a triggered policy. ### Policy Application & Triggering Polices are applied, and policy actions are executed after the following events: * **Scan completion:** Policies are applied to the results of the scan. Triggered policy actions are taken immediately. * **Knowledge base updates:** updates are propagated at specific intervals. During propagation, rules are applied to changes in the most recent scan for your projects which may trigger policy actions. All policies are executed in no specific order. All applicable actions are taken for all triggered policies. {% hint style="danger" %} During policy creation, actions are evaluated to determine similar conditions with conflicting actions, and a notice is generated. However, Threatrix will not prohibit the creation of conflicting policies and/or actions. {% endhint %} # Creating Policies {% hint style="info" %} Roles ROLE\_SUPERADMIN or ROLE\_ADMIN are necessary to create, view, and administer policies. {% endhint %} ### Policy Scopes You can create organizational policies within three scopes; Organization, Entity & Project. You must have administrative privileges to create policies. **Organization Scope:** Policies created at the organization level apply to all entities and all projects for the organization. You can create organization-level policies from the top menu by clicking on Policies. ![Organization scope policies](/files/-MidRsn9gmPvzhfbcV-7) **Entity Scope:** Policies created within an entity apply to direct projects of the entity and all projects of all child entities. Entity-level policies can be created by clicking on the Policy. ![Entity scope policies](/files/-MidSojxIzrNiqyH0fYw) **Project Scope:** Project-level policies are only applied to the project to which they're attached. ![Project scope policies](/files/-MidTFmqGHLWZf9Gx5As) ### Adding a Policy From within the chosen scoped policy administration, click "Add policy." The following screen will be displayed to provide the ability to enter your policy metadata. Security and License policies must be created separately as conditions may not be mixed between them. ![Add policy screen](/files/-MidVTgIzzjyUgy-Lrwk) # Policy Conditions ### Conditions Conditions are the rules that define the policy. Our policy rules architecture allows for conditions to be combined by using operators, similar to SQL. This allows for the creation of very simple or very sophisticated policies. The following are several examples of conditions and their purpose. ![A single condition that will by triggered by any scan with more than 0 High severity vulnerabilities](/files/-Midd2BTlnSYV7xl_XYN) ![A combined condition that will by triggered by any scan with more than 0 High severity vulnerabilities OR a CVSS3 score >= 6](/files/-MideSRMTmOLL_0i2gKy) ![A combined condition that will by triggered by any scan with more than 0 High severity vulnerabilities OR a CVSS3 score >= 6 but ONLY if the count of vulnerabilities that match are >=10. The Auto Adjust flag automatically reduces the condition value "10", to continually lowers the watermark for triggering this policy](/files/-Mider0lmXe_LXoHKpJL) ### Subordinate Conditions Subordinate conditions are qualifiers and apply for all of the conditions contained in the policy. Like conditions, multiple subordinate conditions may be combined with AND/OR operators. Each subordinate condition must be met for the policy to be triggered, even if all conditions are met. Note the following examples: ![This is identical to the last example, above, except that this policy will not trigger unless the Release Stage is Production. ](/files/-MifpCjNy4MncG3EktZJ) ![In this example, the Scope condition is set to "Component" which requires all of the conditions to apply to a single component vs being applied to all scan results. ](/files/-MiftH4fzfSi5VSxWcHh) ![Project tags ensure that your policy is only triggered for projects with the include tags.](/files/-MiftvB7qS5Oe4eWskrS) {% hint style="info" %} Scope conditions apply to current and subordinate scope based on the context of the policy. Organization policies will apply to all entities and projects. Entity policies will be applied to projects for that entity and all projects of subordinate entities. Project-level policies will be applied to that project alone. {% endhint %} # Policy Actions ### Actions Actions are the result of a triggered policy. When a policy is triggered, all of the actions associated with the policy are executed. Policy actions enable notifications or other events to be effectuated as a result of a triggered policy. ### Action Types **Alert:** Email or Slack alerts will be generated by a triggered policy. Configurations for Email and Slack actions are from within the [Admin->Integrations](/administration/organization-settings/integration). **Gate Release:** Choose whether to fail the build based on the triggering of this policy. **Attribute Source:** For license policies, you may choose to automatically attribute source files with the appropriate license. This action causes the license header to be included in your source code and for a pull request to be generated for merging with the main/master branch. **Update Library Version:** For security policies, the component to which a vulnerability is associated may be automatically upgraded to the latest or next secure version. # Policy Scopes Policies may be created and applied with an Organization, Entity, or Project scope. Each policy scope limits its application to those entities, projects, and scans under which the policy is created. **Organization scoped policies**, those created from the top-level Policy menu will be checked against all scan results occurring within all entities and projects that belong to the organization. ![](/files/-Mir5mU5tqXpTtrydt1M) **Entity scoped policies** created from the Policies menu option within each Entity will be checked against all scans for projects associated with the current Entity and all subordinate entities. ![](/files/-Mir6LPuZDzB9HajDRrY) **Project scoped policies**, those created from the Policies menu option within each Project, will be checked against all scans in the current project. ![](/files/-MirC4GRoKVKpzidB8Hg) ### # User Management ## Inviting Users Authorized users may invite new users directly through their profile by using the Invite User feature, as shown below. #### 1) Select "Invite User" from the user profile drop-down menu

#### 2) Complete the invite user form You have the ability to modify the subject and contents of the email by deselecting the custom checkbox options. ![Invite user form](/files/-MhVmBhSmfivu63lsvfq) # Organization Settings Integration, account, billing and other settings related to your organization # Organization Knowledge Base ## What is the Organization Knowledge Base The organization knowledge base allows for the creation and management of custom licenses, components and asset matches that can be automatically assigned to artifacts during scanning. ## How is it used The custom KB values will override the default values assigned to an artifact, by Threatrix, during the scan process. This enables your team to: ### **Components** * Assign a component(name, license(s), copyrights, vulnerabilities, etc) to an unmatched component which will override the default values assigned by Threatrix * Override a the values of a matched component(name, license(s), copyrights, vulnerabilities, etc) with the component values from your organizations knowledge base ### Assets * Override a the values of a matched matched asset(origin, license(s), copyrights, versions, etc) with the origin match values from your organizations knowledge base * Assign a multiple origins, with it's associated attributes, to an asset. ### **Licenses** Custom licenses may be added to your organizations knowledge base and then applied to Components or Assets withing the project review workflows.
# Integration ### **Emails** All emails in this list will receive notifications for alerts driven by a triggered policy with "Email" configured as an alert option.

### **Slack** All channels included in this list will receive notifications for alerts driven by a triggered policy with "Slack" configured as an alert option. See [Slack Integration](/administration/organization-settings/integration/slack) for complete details.

# Slack Integration Slack integration allows your team to be alerted via slack channels. All slack channels included in this list will receive notifications for alerts driven by a triggered policy action with action type "Alert" and name "Slack" configured as an alert option. #### **Configuring Slack Channels** Threatrix App must be added to your Slack account for Threatrix slack alerts to be successfully delivered. #### **Adding Threatrix App to Slack** Use the following Slack documentation to Create a Slack app. We will walk you through each step. {% embed url="" %} 1\) Under Create Your Slack App, click the "Create Your Slack App" button. ![](/files/-MirFLWS348jLN1E5l2W) 2\) From the "Create your Slack app" screen, click the "Create New App" button. ![](/files/-MirFqLhyDdu30jsbgC8) 3\) Select "From Scratch" from the popup dialogue box. ![](/files/-MirG4dS5hPiUwNxlHA_) 4\) From the "New app & chose workspace" dialogue, enter "Threatrix" for App name and select a workspace from the "Pick a workspace" dropdown. ![](/files/-MirGVgDGaU5FVUtiKhF) 5\) Once your app is created, you'll be redirected to the Basic Information for your app. From this page, under Add features and functionality, select "Incoming Webhooks." ![](/files/-MirHjOqiE6SKYuO-I2i) 6\) On the "Incoming Webhooks Page," Activate incoming webhooks. ![](/files/-MirI2_bzEoG3WcfrHOk) 7\) Once Webhook is activated, scroll down and click the "Add New Webhook to Workspace" button. ![](/files/-MirIMYqfofiJrvZjlhS) 8\) Next, you must select a channel where you want alerts to be delivered from Threatrix. Select a channel and click "Allow." ![](/files/-MirInssv-Fx1eL89HXF) 9\) You'll be redirected to the Webhooks configuration with a freshly minted Webhook URL that we can use within Threatrix. Select the "Copy" button to copy the URL to your clipboard. ![](/files/-MirJEk6Rwl4FUS2MfKk) 10\) From within Threatrix -> Admin -> Integration -> Slack click "Add Slack URL" ![](/files/-MirVuPdL3AGgWxzoQWv) Within the "Add Slack URL" dialogue, enter the copied Slack URL and click "Save." ![](/files/-MirWF6nXnoSelKLaf9b) **Your Slack alert Channel is now configured and ready to go!** # Jira Integration Jira integration allows your team to be alerted via Jira tickets. When configured with the right Project Key, Login and API token, you will receive notification for alerts driven by a triggered policy action with action type "Issue" and name "Jira" configured as an alert option. #### **Configuring Jira** To configure Jira, you need to first ensure you have access to Jira administration and identified the Project and associated account and API token created ahead of time. See screen shots below to give you an idea as to how to structure projects. Setup Jira Projects

Obtain project keys, issue types, login e-mail and API Token.

[Create your API Token](https://id.atlassian.com/manage-profile/security/api-tokens). Make sure to copy this in a safe place. You will need this to configure the Jira Integration with Threatrix.

Now you are ready to configure JIRA Integration under Admin/Settings/Integration/Jira Integration.

**Your Jira Integration is now configured and ready to go!** # Service Keys API Keys provide for authorized access to our API and allow for integrations with various tools, including Threat Agent, to perform automated scans from with your build environment. ### Creating an API Key Click "Add API Key" to begin the process. ![](/files/MCPCfcsi5H2f929rip6p) Once you're on the API Key Create/Edit screen, enter a Title for your key and optional description. The Title should reflect the intended use of the key. Some examples might include: * Threat Agent * Build Server * Circle CI ![](/files/B9dG2UzdjBpidcbdwz4R) ### API Key Permissions API Key permissions reflect the identical permissions of the user who creates the key. # RBAC Threatrix role based access control plays an important role in the security of our platform. Roles are enforced throughout Threat Center and across the entire Threatrix ecosystem, including our API. ### Role Composition Roles are composed of permissions that grant access to granular micro and macro features across the Threatrix ecosystem. Nearly every feature is protected by the RBAC, which allows user administrators to construct custom roles based on the needs of each group or individual user. As roles are enforced within both Threat Center and our [API,](/graphql-api/api-overview) configuring permissions and created roles is an important step in securing your sensitive data from unauthorized access. ### Out of the Box Roles These roles are intended to get you up and running quickly. Available roles and permissions are as follows: ![](/files/-MisjylfRnN2J7OiR5EZ) # Entity Management All projects are attached to an [Entity](/resources/dictionary#entity). Small organizations may create only a single entity under which all projects exist. Within large organizations, the number of projects under a single entity tends to become unwieldy. To resolve this issue, we allow organizations to create entities that reflect the hierarchical structure of their teams. When you log in, you are automatically dropped into your default business unit entity. From here, you can access all of the projects you are authorized to view, as shown below. ### Adding an Entity Adding a new Entity to your entity tree can be accomplished using the Entity Manager. The Entity Manager can be found under the Admin link on the top menu bar. ![](/files/-Misls9nCvBCz0F1mDiI) By default, only the root Entities are displayed, which are those directly attached to the organization. However, you may open each to display the entire Entity tree. ![](/files/-MismJAkRgKK-60m24KH) Selecting an Entity from the Entity Tree provides you with the ability to add a child Entity. Click "Add Entity" and, from the provided dialogue, enter the child Entity name and type and click "Save." ![](/files/-Misn78qI2caIEjr4MMQ) The new Child entity will appear in the Entity tree. ### Renaming an Entity Select the Entity you wish to rename from the Entity tree on the left. The Entity information will appear on the right and be edited accordingly. Renaming your Entity will not change the EntityID. ![](/files/-MisnsMdPBtE1IuLDWjT) ### Removing an Entity You may remove an Entity if it meets the following criteria: 1. The Entity has no child Entities 2. The Entity has no projects # Okta # Okta Org2Org Integration These instructions wil guide you through the process of creating an Okta org2org integration with Threatrix. ## Overview This integration enables members of your team to seamlessly authenticate into the Threatrix app with granted permissions. This integration requires a 3-step process * [Create org2org app](#step-1-create-an-org2org-app): The customer configures Threatrix org2org integration in their Okta account * [Threatrix IdP setup](#step-2-threatrix-idp-setup): Necessary credentials are provided to Threatrix to complete customer integration with Okta. * [Complete Setup](#step-3-complete-org2org-setup): The customer completes org2org integration configuration The total setup and configuration time is **approximately 20 minutes**. ## Step 1: Create an Org2Org app \ Login to your Okta administration console and navigate to Applications->Applicatons. Click Brows App Catalog

Select or search "org2org"

Click "Add Integration"

Give the integration a name. “Threatrix Integration (Org2Org)” for example.\ Input into Base URL field.\ Leave other fields default and proceed.

On the next page select SAML 2.0

Scroll down and click “Setup Instructions”

On the page which just has opened navigate to step 6. Copy and save “IdP Issuer URI”, “IdP Single Sign On URL” and download the certificate.

Back to Org2Org setup page, scroll down and paste into “Hub ACS URL” and “Audience URI” fields and click Done.

## **Step 2: Threatrix IdP Setup** Provide the above URI, URL, and certificate to the Threatrix team. ## Step 3: Complete org2org Setup Putting actual values for “Hub ACS URL” and “Audience URI” fields. Go to “Threatrix Integration (Org2Org)” app page, Sign On tab and click Edit.

* Scroll down to “Advanced Sign-on Settings” section and input data. * Into "Hub ACS URL" field input value of "Assertion Consumer Service URL" field provided by the Threatrix team. * Into "Audience URI" field input value of "Audience URI" field provided by the Threatrix team. * Click Save.

Setup provisioning

Enable API integration, input API token provided by the Threatrix team, click “Test API Credentials” to make sure the token is ok, and click Save.

After adding the token you’ll see the Provisioning tab with the “To App” section selected, click Edit.

Make selections like those shown in the screenshot below and click Save.

**Create Treatrix-related groups.**\ Groups are required to identify the organization to which users belong and the user roles. Go to the Directory/Groups page and create group with the prefix "TRX\_ORG\_" which will determine organization and groups with the prefix "TRX\_ROLE\_" which will define user roles.

Then go to the Directory/People page and add groups to desired user(s).

**Add the Push Groups Rule** Go back to the Threatrix integration (Org2Org) page, Push Groups tab and add the rule.

Name it "Push Threatrix Related Groups", add filter by prefix "TRX\_" and click Save.

Now assign the Threatrix Integration (Org2Org) app to people as shown in the next several screenshots

**That’s it**! You've completed the setup of Threatrix SAML/Okta org2org Integration. # API Overview GraphQL is a query language for our API. It's beneficial for large datasets as it allows for selecting specific objects and fields rather than committing to all data returned by a REST API endpoint. GraphQL is very beneficial for large datasets as it provides for greater flexibility and higher performance API endpoints. Send a GraphQL query to our API and get exactly what you need. GraphQL queries always return predictable results. Additionally, it allows us to evolve our API without the need for versioning. If you're not familiar with GraphQL, we suggest that you check it out from the link below. {% embed url="" %} ### GraphQL Endpoint While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request. Apps using GraphQL can be quick even on slow mobile network connections. Our GraphQL API is located at: ``` https://app.threatrix.io/graphql ``` Our GraphQL is self-documenting. As such, documentation is provided from our GraphQL Explorer endpoint that allows for exploration, documentation, and live queries testing against our API. Visit our GraphQL Explorer tool here: ``` https://app.threatrix.io/graphiql ``` ### Authentication Our GraphQL API endpoint requires authentication with an API token. Generate user API token [Generate Admin API token](/administration/organization-settings/integration/api-keys) Example Queries # Dependency Managers # PIP Python3

sudo apt install python3-testresources

Python2 ``` sudo apt install python-testresources ``` # Dictionary Common words and phrases to assist with context of documentation and discussions surrounding Threatrix, the Software Composition Analysis space and application security. ### Asset ### Dependency Manager ### Declared ### DevOps ### DevSecOps ### Discovered ### Embedded Asset ### Entity An Entity may represent a team or group of associated people assigned to the Entity for a common purpose. Entities provide a structure within Threat Center that emulates how your organization is structured as a tree pattern. Your organization represents the root of the tree to which Entities may be attached. Entities can represent any person, group of people, teams, divisions, or business units with your organization. ### GUID ### Permission ### Organization ### Role ### Scope ### Secure Version Represents a version of a component with no known vulnerabilities. ### SBOM **S**oftware **B**ill **O**f **M**aterials ### Static Reference # Licenses Metadata associated with licenses within the Threatrix ecosystem. ### License Categories * **UNDEFINED**: Unknown or undefined category * **UNLICENSED**: No license could be discovered, but limitations and conditions may still apply to the work. Based on the source of the work, there may be an implied license. * **PROPRIETARY\_FREE:** Proprietary Free software may not require a commercial license but may have specific terms and conditions. These terms and conditions may be in the code or clickable downloaded licenses. * **PUBLIC\_DOMAIN:** Available to use software without explicit obligations. It has a license notice that must be distributed with the source code as described in the license. The match may be to software, published public domain specifications, or another type of publication. * **PROPRIETARY:** Proprietary source-available software, which has available source code but is not classified as free software or open-source software. In some cases, this software is originally sold and released without the source code, which becomes available later. Source-available software is software released through a source code distribution model that includes arrangements where the source can be viewed, and in some cases modified, but without meeting the criteria to be called open-source. * **PERMISSIVE:** A permissive non-copyleft software license, sometimes called BSD-like or BSD-style license, is a free software license with only minimal restrictions on how the software can be used, modified, and redistributed, usually including a warranty disclaimer. * **COPYLEFT:** Open source software that offers irrevocable permission to the public to copy and redistribute the work in the same or modified form, but with the conditions that all such redistributions make the work available in a form that facilitates further modification and uses the same license terms. A copyleft license can require code interacting with copyleft licensed code to be licensed the same way. * **COPYLEFT\_WEAK**: free software licenses that mandate that source code descended from software licensed under them will remain under the same, weak copyleft license. However, one can link to weak copyleft code from code under a different license (including non-open-source code) or incorporate it in a larger software. Otherwise, weak copyleft licenses allow free distribution, use, selling copies of the code or the binaries (as long as the binaries are accompanied by the (unobfuscated) source code), etc. Some free software licenses don’t establish an obligation of licensing derivative work in the same terms as the original work license. But they come with some requirements, such as distribution of the source code or dual licensing. * **COPYLEFT\_LIMITED:** A license requiring you to redistribute source code including your changes and provide attribution for the software authors. Your obligation to redistribute source code, including proprietary code linked with code under this license, is limited according to license-specific rules. * **COPYLEFT\_PARTIAL:** copyleft partial exempts some parts of the work from the copyleft provisions, thus permitting distribution of some modifications under terms other than the copyleft license, or in some other way does not impose all the principles of copylefting on the work. * **COPYLEFT\_STRONG:** Strong copyleft licenses go a step further from weak copyleft licenses and mandate that any distributed software that links or otherwise incorporates such code be licensed under compatible licenses, which are a subset of the available open-source licenses. As a result, these licenses have been called “viral.” * ### Styles ### Origin * COMPONENT: License was declared for the component * REPOSITORY: The license was discovered within the source repository (Github, Gitlab, etc.) * REPOSITORY\_META: The license was declared to the repository(Github, Gitlab, etc.) * REPOSITORY\_LICENSE: The license was declared within the LICENSE file in the source repository * ASSET: The license was discovered within an asset in the source repository. ### Discovery Type * **Discovered:** The license was found by our ingestors within a source file or metadata file. * **Declared**: The license was declared by the dependency manager or attached to the source or release repository for the component. ### Copyrights All copyrights for discovered licenses are extracted from the license data source (LICENSE file, source code, etc.) and included in the results. Accurate copyrights are required to provide proper attribution for the license. Copyrights can be found within scan results -> Licenses -> License details -> Copyrights tab. ### Attribution Some licenses require the license header and/or copyrights in various, conspicuous locations. Threatrix embedded open source detection will find any open source that your team has included in your proprietary source code and accurately determine the license for the embedded open source. An example is shown below: ![](/files/-Miw5eVgGXSom09Npqtk) Source attribution can be applied manually, directly from the embedded asset detail screen by selecting the licenses you want to apply attribution to in your source code. Then select "Attribute Licenses." ![](/files/-Miw6VLL58uY-EDJc3xR) From the Attribute Licenses dialogue, select an Attribution status and enter an optional comment, which will be included in the attribution notice in your source code. ### Attributes License attributes are a summary of the important permissions, limitations, and conditions of a license. They make it easier for your team to understand the requirements. An example of Apache 2.0 license attributes is shown below. Each attribute provides a full description available by hovering over the questions mark icon to the right of the attribute. ![](/files/-Miw0LaqvhPnm_oQar2d) # Security & Privacy Personally Identifiable Information ## Scan Data Collection ### Threat Agent Data Collection During scans that occur while using [Threat Agent](broken://pages/-MbsuX1mY6CMyF3-UEMA), will collect the following data. * Dependency manager files * File Metadata * File name * File size * File locations relative to the root of the project * Whole file SHA1 signatures * File DNA signatures(As part of TrueMatch) {% hint style="success" %} Threat Agent does not collect or transmit your source code to our server during standard scans. {% endhint %} {% hint style="warning" %} **SOURCE CODE** will be collected and transmitted to our server if you select the `--cloud-scan` option when launching Threat Agent. {% endhint %} ### ThreatScan Data Collection ThreatScan integrates directly with your authorized SCM; Github, Gitlab, or Bitbucket. During scans, a copy of your code is transmitted to our scan server, processed, and then destroyed. No copy of your code ever remains on our servers. * # Binary File Support # Getting Started This documentation will walk you through how to get your Threatrix Hybrid Platform installed and configured with your on premise or cloud Version Control Systems (VCS). Please make sure you are familiar with various components of the Threatrix Platform before proceeding and you have met the requirements for your hybrid install and configuration. ## Threatrix Hybrid Installation Prerequisites * [ ] You have access to the Internet from your Hybrid Environment * [ ] You have access to [https://app.threatrix.io](https://app.threatrix.io/) * [ ] Cloud or On-Prem SCM operational and accessible (optional) * [ ] You have root or superuser privileges (via sudo) to set up and configure your Hybrid Environment * [ ] You must be granted permissions to access the Threatrix Hybrid Platform image on Dockerhub. Please reach out to to request permission. * [ ] You have met the minimum requirements for installing Threatrix Hybrid Platform * Linux VM is recommended. Windows is supported, but experimental * At least 8 vCPU Intel or AMD * 32 GB of RAM * 50 GB of storage * Docker installed on the VM # Installation To perform a fresh installation of the Threatrix Hybrid platform, make sure you have satisfied all the requirements identified in the [Getting Started](/) section. Please follow the steps below: #### Download and Run the Installer ```bash $ mkdir threatrix-software $ cd threarirx-software $ wget https://raw.githubusercontent.com/threatrix/hybrid/master/install $ chmod +x ./install ``` #### Login to Dockerhub ``` sudo docker login -u {USERNAME} ``` #### Usage ```bash $ ./install -h Welcome to Threatrix Hybrid Install Fri Aug 11 19:28:45 UTC 2023 Usage: install -h -u -a -d -h : Help -u : Version of the UX image you want to upgrade to. Default is latest -a : Version of the APP image you want to upgrade to. Default is latest -d : Version of the DB image you want to upgrade to. Default is latest -p : Port number which threatrix applcation can use. Default is 80 ``` #### Run the Installer ```bash $ ./install Welcome to Threatrix Hybrid Install Fri Aug 11 17:59:55 UTC 2023 Installing the following components in your Hybrid Envirnment: Threat Center: latest APP : latest DB : latest Rabbit MQ : rabbitmq:3 Do you want to continue? ( y or n ) y Proceeding with install... Downloading Containers.... Threatrix Network exists! Starting containers.... Waiting for database to initialize.... Creating schemas.... Starting Threatrix Components.... Installed the following versions of Threatrix components in your Hybrid Envirnment: Threat Center: 23.08.11.1 APP : 23.08.11.1 Use the following URL to access Threat Center: http://hybrid-upgrade.us-central1-a.c.core-247502.internal:80/ Threatrix Hybrid installation complete! Fri Aug 11 18:05:04 UTC 2023 ``` Now you are ready to take Threatrix for a test drive! # Upgrade To upgrade your hybrid environment please follow the steps below. #### Download the Update Script ```bash $ cd threarirx-software $ wget https://raw.githubusercontent.com/threatrix/hybrid/master/update $ chmod +x ./update ``` #### Usage ```bash $ ./update -h Welcome to Threatrix Hybrid Update Utility Fri Aug 11 18:10:38 UTC 2023 Usage: update -h -u -a -p -h : Help -u : Version of the UX image you want to upgrade to. Default is latest -a : Version of the APP image you want to upgrade to. Default is latest -p : Port number which threatrix applcation can use. Default is 80 or 443 based on -s option ``` #### Upgrade Your Environment ```bash $ ./update Welcome to Threatrix Hybrid Update Utility Fri Aug 11 18:15:32 UTC 2023 Updating your Hybrid Environment with the following components: Threat Center: latest APP : latest Do you want to continue? ( y or n ) y Proceeding with install... Threatrix Network exists! Updating Threatrix App and Threat Center.... Restarting Threatrix App and Threat Center containers.... Upgraded the following Threatrix components in your Hybrid Environment: Threat Center: from 23.08.11.1 to 23.08.11.1 APP : from 23.08.11.1 to 23.08.11.1 Use the following URL to access Threat Center: http://hybrid-upgrade.us-central1-a.c.core-247502.internal:80/ Threatrix Hybrid update complete! Fri Aug 11 18:16:09 UTC 2023 ``` Now your upgraded environment is ready for use. # Setup If you have not done so already, you must [install the Threatrix Hybrid Platform ](https://docs.threatrix.io/hybrid/installation)before completing these steps. ## Cloud API Token [Anonymous portions of your scan ](https://docs.threatrix.io/hybrid/cloud-data-disclosure)are sent to Threatrix cloud environment to be matched with our cloud knowledge base. Cloud access from your Hybrid deployment requires a Cloud API Token generated for your account. If you do not have a Cloud API token, please reach out to before you continue. ## Create Super Admin Hybrid Account Your first step is to create an account on your new Threatrix Hybrid deployment. This is available at http\://{YOUR\_HYBRID\_IP\_OR\_DOMAIN}/create-account. The first user will create an account with username(email) & password. This can be changed later after you've setup integrations with your on premise source control management system for OAuth authentication. The first user is granted SUPER\_ADMIN permissions. Once you've created an account, you'll be automatically logged into Threat Center. Future logins are possible at http\://{YOUR\_HYBRID\_IP\_OR\_DOMAIN}/login ## Enable Hybrid Configuration Once you've created an account, you'll need to configure your local instance as a Hybrid instance. 1. Navigate to Admin -> Deployment Mode 2. Select "Hybrid" from the drop down list 3. Enter your API Token provided to you by Threatrix 4. Click Save button 5. Use your browsers "Refresh" feature to reload Threat Center and activate your account. Selecting "My Team" from the top menu will redirect you to your teams page, shown below. From this page you can choose to evaluate all available products. Video demonstrations are available to help you quickly get started with your evaluation.

## Invite other users You can invite your team members using an Invite URL available under your profile. Click on your profile icon, in the top right corner, then choose "Invite User". This will create an Invite URL that you can send out to your team to invite them to use Threatrix. # Cloud Data Disclosure Anonymous portions of your scan are sent to Threatrix cloud environment to be matched with our cloud knowledge base. Data is transmitted to our server using 256bit encryption. None of the data that's transmitted to our cloud is ever persisted. It's stored in memory during processing and immediately expunged from memory after use. Your scan results data are stored in your local, on premise, database for your Threatrix Hybrid deployment and only available to you. Threatrix does not have access to your scan results. The following data is sent to our cloud with every scan: 1. Software bill of materials for each supported dependency manager in your project. This data is used to build a dependency tree for declared dependencies and returns the associated licenses and vulnerabilities. 2. Random cryptographic hashes derived from portions of your source code. This data is used to determine what parts of your source code are open source and return the associated provenance and license data. 3. source file names 4. source file size # Troubleshooting ## Permission Denied If you see en error like this one, it means that you do not have the appropriate permissions. ``` permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.45/containers/threatrix-threat-center/json": dial unix /var/run/docker.sock: connect: permission denied permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.45/containers/threatrix-hybrid-app/json": dial unix /var/run/docker.sock: connect: permission denied ``` Uninstall the containers and reinstall with sudo, as follows: ``` sudo docker stop threatrix-threat-center threatrix-hybrid-app rabbitmq threatrix-db ``` ``` sudo docker rm threatrix-threat-center threatrix-hybrid-app rabbitmq threatrix-db ``` ``` sudo ./install ```