Understanding Custom Rules for Agent-Based Scanning

Veracode Software Composition Analysis

Custom rules help you take greater control of your software delivery workflow.

Rules are sets of controls to which your codebase must adhere. Veracode Software Composition Analysis agent-based scanning has always shipped with default rules, which are hard-coded and applied to all workspaces.

The custom rules feature in agent-based scanning exposes the controls that the rules engine uses. It allows you to edit these controls per workspace and decide what actions to take when projects violate controls, ensuring that no software ships unless it meets your security requirements.

When projects violate a control, you can choose to create an issue to track a problem, break the build, or both. Set your own severity for different kinds of control violations, which will be used as the severity for agent-based scanning issues and as the exit code when a build is broken. You cannot create custom rules for a workspace if your organization enforces organization rules.

Finally, this feature contains improvements for all organizations, including recognizing ignored issues in the agent, and more granular issue severities in lists of issues.

Structure of a Rule

There is one rule per workspace. Every project in a workspace inherits the workspace rules.

Each rule is composed of one or more controls. A control checks for specific rules.

A control is structured as follows:

  • Properties
    • Control Name
    • Severity
    • Level
  • Condition
    • Resource
    • Matcher
    • Descriptor
      • Parameters for vulnerability descriptors
        • Severity
          • Check for a vulnerability of high, medium, or low risk. The level of risk that a vulnerability has is determined by its CVSS score. Veracode SCA supports the use of vulnerability severities based off of either CVSS v2 or CVSS v3 scores.
        • Vulnerable Method
        • Override Control Severity with CVSS Score
      • Parameters for license descriptor
        • Kind
          • Check for specific licenses by name or select a risk rating.
        • Including
          • If you select License by name, select the licenses to include in the rule.
        • Excluding
          • If you select a risk rating, select the licenses to exclude from the rule.
  • Action
    • Create Issue

Properties of a Control

A control’s properties are basic fields that identify a control and its severity.

  • Control Name: a string that helps you quickly identify the control
  • Severity: a number from 0.1 (lowest) to 10.0 (highest) that lets you determine how serious a control violation is considered in this rule. If you choose to create an issue when a control is violated, the severity of the issue is defined by the severity of the failed control. Severities appear on lists of issues to make them easier to rank.
    • Note: Severity is different from a vulnerability risk (CVSS) score. However, if you wish to use the CVSS score as the severity for vulnerability issues, you can set that option (see Descriptorbelow).
  • Level: there are two levels
    • Error: A level of error means that a non-zero will be returned, which can be used (for example, by CI build scripts) to break a build. The exact value of the exit code depends on the severity of all controls which were violated. See note below for more details.
    • Warning: A level of warning will return an exit code of “0” which can be used to allow the build to continue.
    • Note: To determine the exit code for a scan, enter echo $? in the CLI after the scan concludes. If “0” is returned, that means no controls of level error were violated. If a number greater than “0” is returned, that means a control of level error was violated, and the number reflects the highest-severity control that was violated, rounded to the nearest integer.

Conditions of a Control

A control condition is a rule to enforce, such as library should not contain high-risk vulnerabilities.

A condition is made up of three parts:

  • Resource: the entity which is being inspected for certain conditions. Currently, Veracode SCA agent-based scanning can inspect libraries with four dependency relationships
    • Any: a library which is either referenced in your configuration file or used by a direct dependency. Encompasses all your libraries.
    • Direct: a library which is specifically referenced in your configuration file
    • Transitive: other libraries which are used by the direct dependencies
    • Both: a library which is both referenced in your configuration file and used by a direct dependency
  • Matcher: a comparison operator that defines how the resource will be inspected. The current values are should not contain and should be.
  • Descriptor: the descriptor and its parameters define the checks performed against the resource. The current descriptors available are vulnerability, license, and library.
    • Veracode SCA agent-based scanning can check that:
      • A library should not contain vulnerabilities with certain parameters (goes with matcher should not contain)
      • A library should not contain licenses with certain parameters (goes with matcher should not contain)
      • A library should be the latest version (goes with matcher should be)
    • Parameters for vulnerability descriptor
      • Severity: check for a vulnerability of high, medium, or low risk
      • Vulnerable Method: check for vulnerabilities where vulnerable methods were or were not found
      • Override Control Severity with CVSS Score: for vulnerability issues only, you can choose to set the severity of the violated control to the CVSS score of that vulnerability instead of manually assigning a severity. See Properties of a Control.
    • Parameters for license descriptor
      • Kind: check for specific licenses by name or check for licenses with a selected risk rating. You can exclude specific licenses by name from the risk rating parameter.

Actions of a Control

A control’s action defines what happens automatically when the condition evaluates to false.

  • Create Issue: When checked, an issue will be created when the condition is false and the control is violated at scan time. Currently this is the only action available.
    Note: At this time, issue creation from a rule will not automatically create issues in third party applications. However, if you have an integration to Jira or GitHub set up for agent-based scanning, you can manually create a Jira or GitHub issue from a Veracode SCA issue in the Veracode Platform.

Example: High-Risk Vulnerabilities with Vulnerable Methods

There should be no CVSS v2 high-risk vulnerabilities where vulnerable methods are found. If there are, assign a severity of 10, break the build, and create a Veracode SCA issue.

Example: Medium-Risk Vulnerabilities Without Vulnerable Methods

There should be no CVSS v3 medium-risk vulnerabilities where vulnerable methods are not found. If there are, use the vulnerabilities’ CVSS score as the control severity, do not break the build, but do create a Veracode SCA issue.

Example: Allow Low-Risk Vulnerabilities Without Vulnerable Methods

Suppose an organization is not interested in tracking low-risk vulnerabilities where no vulnerable methods were found. Simply delete any controls where Descriptor = vulnerability, Severity = low risk, and Vulnerable Method = no. Then at scan time, no Veracode SCA issues for this kind of vulnerability will be created.

An alternative way of accomplishing the same outcome is to deselect the Create Issue checkbox in a control where Descriptor = vulnerability, Severity = low risk, and Vulnerable Method = no. You might prefer this method if it is possible that you will want to create Veracode SCA issues for this control in the future, and don’t want to recreate it at that time.

Example: High-Risk Licenses with Exceptions

If your condition rejects libraries that contain high-risk licenses, you can select one or more specific high-risk licenses to allow. In this example, you allow one exception for Open Software License 1.0.

Example: Out-of-Date Libraries

All direct libraries should be up to date. If any are not, do not break the build, but do create a Veracode SCA issue with severity = 1.



Veracode Default Rules

Using the Veracode default rules, issues get created when:

  • A vulnerability exists in either direct or transitive libraries.
  • A direct library is out of date.
  • A direct library contains a high-risk license.

Additional controls that you can use with custom rules include:

  • A library has multiple licenses.
  • A library has no license.

The issue severities are set as follows:

  • Vulnerability issues, direct or transitive: the vulnerability’s CVSS score
  • Outdated library issues, direct: 3.0

Organization Rules

Organization rules allow you to apply the same set of controls to all of your workspaces. If your organization enforces organization rules, you cannot set custom rules at the workspace level. If your organization has configured organization rules but does not enforce them, you can select the organization rules when configuring the rules for a workspace.

Organization rules selected

When to Set Up or Modify a Custom Rule

If the Agent-Based Scanning default rule above meets your needs, you do not need to modify it.

However, you may have your own tolerance to certain conditions. Perhaps you do not need an issue to be generated if a library is out of date or if a library has a low-risk vulnerability. In cases such as those, you should set up a custom rule for your workspace.

Who Can Set Up or Modify a Custom Rule

You must have the Security Lead, Workspace Administrator, or Workspace Editor role to edit or add custom rules for a workspace. You must have the Security Lead role to edit, add, or enforce rules for an organization.

Viewing Rules

  1. In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
  2. Click the Agent-Based Scan tab.
  3. Either select a workspace to view workspace rules or click Agent-Based Scan Settings to view organization rules.
  4. Click Rules.

View-only vs. Edit Mode

By default, a rule displays in view-only mode. The details of each control are initially collapsed.

Expanding and Collapsing a Control

To view the details of a control, click the right-pointing chevron.

Using the Default Rules

If you do not customize the workspace rules, Veracode SCA applies the default rules.

Navigate to the workspace, open the Manage Workspace section, and click Rules. If Veracode Defaults is selected in blue, there is no further action you need to take.

To use the default rules after setting up a custom rule, click the Veracode Defaults tab. This selection makes the default rules active for any future scans in that workspace.

Setting up a Custom Rule

  1. In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
  2. Click the Agent-Based Scan tab.
  3. Either select a workspace to view workspace rules or click Agent-Based Scan Settings to view organization rules.
  4. Click Rules.
  5. Click the Custom Rules tab.

    A copy of the default rules appears.

  6. Click Edit to enter edit mode.

Editing Custom Rules

  1. In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
  2. Click the Agent-Based Scan tab.
  3. Either select a workspace to view workspace rules or click Agent-Based Scan Settings to view organization rules.
  4. Click Rules.

    The currently applied custom rules appear.

  5. Click Edit.

    The controls change from view-only mode to edit mode. The details of each control are collapsed by default.

  6. Make your adjustments and, then, click Save.

    For instructions on how to define a control, see Structure of a Rule and Adding, Removing, and Rearranging Controls.

Once you save, the custom rules are active for any future scans in that workspace.

Resetting Custom Rules

You may want to update your custom rules by starting over from the default rules and making new customizations.

To reset your custom rules to the default rules:
  1. In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
  2. Click the Agent-Based Scan tab.
  3. Either select a workspace to view workspace rules or click Agent-Based Scan Settings to view organization rules.
  4. Click Rules.

    The currently applied custom rules appear.

  5. Click Edit.
  6. Click Veracode Defaults.
  7. Click Reset rules.

This action discards any customizations, resets all controls to the default rules, and applies the changes immediately.

Adding, Removing, and Rearranging Controls

When a rule is in edit mode, you can add new controls, remove controls, and move controls up and down.

To add a new control, click the Add Control button below the last control row.



To remove a control, click the trash can icon at the far right.



To move controls up and down, use the up and down arrows next to the trash can icon.

In general, the order of controls in a rule does not affect which issues will be created, whether a build is broken or not, or the order in which controls are evaluated. It allows you to visually group controls together in an order that is meaningful to you. However, if you create two near-identical controls (e.g., high severity vulnerabilities with vulnerable methods) that only differ by a property (e.g., one control specifies “8” and another specifies “10”), the control furthest down the list takes precedence.

How Rules Work at Scan Time

At scan time, the scanner identifies open-source libraries in your code and any transitive library dependencies, generates a dependency graph and a call graph, and then sends the results of the scan to the Veracode Platform.

Veracode checks the scan results against each control in the rule. If a control fails, the specified action for that control is triggered, and the highest severity of the violated controls is returned as the exit code.

CLI Output

With the rules feature, the CLI returns a list of issues generated based on the rules:

Viewing Issues

After scanning, you can view your issues as usual in the Issues report or the Issues tab of a project.

With this release, the Severity column on lists of issues will display numerical values instead of icons for low, medium, and high.

In addition, for custom rules, if you manually enter severities for rule controls regarding vulnerabilities, Veracode SCA uses that value for the issue severity.

For example, medium-risk vulnerabilities with vulnerable methods were assigned a 9 whereas high-risk vulnerabilities without vulnerable methods were assigned an 8. These appear in the project Issues tab like this:



However, using the default rules, the same medium-risk vulnerabilities with vulnerable methods appear much farther down on the list, as the severity is based on CVSS scores only:



Ignoring Issues

Once you ignore an issue in the user interface, that issue no longer contributes to build failure. For instance, if you have a control that creates a Veracode SCA issue and breaks the build for medium-risk vulnerabilities, and a medium-risk vulnerability is found, a Veracode SCA issue is created and the build breaks. If you then ignore that issue in the Veracode Platform and scan again, Veracode SCA is aware of that issue in the Ignored list, and allows your build to continue. This feature helps reduce false positives and lets you continue your work uninterrupted.