Skip to main content

Restrict behaviors

The Spectra Assure platform identifies a variety of behaviors in your software during analysis.

In the context of Spectra Assure, software behaviors (or simply "behaviors") are defined as human-readable descriptions of code intent. Derived from complex code patterns, these descriptions clarify the capabilities of the analyzed software. During analysis, Spectra Assure collects code patterns, metadata, and file content that must be triggered by specific reasons to be identified as software behaviors.

Each file can exhibit more than one behavior, but some are more problematic than others. To see whether a behavior might be suspicious or even malicious, pay attention to the type of the software and its basic functionalities, as well as the expected software intent and the community prevalence information for the behavior. Any detected discrepancies can be the signs of potential software tampering.

For this reason rl-secure lets you restrict any unusual behaviors by creating a new processing filter in your policy configuration file.

When you restrict certain behaviors through policy configuration, you are telling rl-secure that these behaviors are not in line with the expected functionalities of the software and should therefore raise a warning or even fail the build.

Behaviors in the policy configuration must be specified either by their unique IDs or by the category they belong to. To target a specific behavior, you must provide its full ID (for example, BH12858). You can copy the behavior ID directly from the analysis reports, or from the full list of behaviors in the reference documentation. To target all behaviors that belong to the same category, you can either copy the category name from the full list of categories or directly from the Behaviors page of analysis reports.

Therefore, you can modify policy configuration files to restrict the following:

The approach you'll choose primarily depends on your use case.

Examples in this guide show how to modify the policy configuration for existing projects and packages in a previously created package store. If you haven't yet created any projects and packages, follow the instructions in the quick start guide.

Policy configuration fields

Behavior restrictions use the following policy configuration objects and their fields:

  • processing.filter.hunting.categories
  • processing.filter.hunting.behaviors

Consult the policy configuration schema for details on all supported options.

Restrict entire behavior categories​

In this example, all projects in a package store exhibit some undesirable behaviors that can potentially indicate your software has been tampered with. Multiple critical behaviors have been found only in two categories - network and evasion. We want to call attention to them by either only issuing a warning (TH15101) and triggering a failing policy (TH15102).

To do this, we're modifying the policy configuration file for the entire package store (the .repository_policy.info file). When changes are synchronized, the configuration will apply to all projects, packages and versions in the package store.

Specifically, we're creating a processing filter that will look for all behaviors that belong to the specified behavior categories and trigger the appropriate policies.

1. Modify package store policy settings​

1) In the rl-secure package store, navigate to the policy configuration file in the root directory and open it in a text editor. In this example, the full path to the file we're editing is /home/armando/my-repository/.repository_policy.info.

2) In the .repository_policy.info file, add the hunting section.

  • To ensure that the filter is applied when analyzing files, set enabled to true.
  • With matches set to "file" and pattern set to "*", the filter will target all files across package versions. We're using this because behaviors are always tied to specific files.
  • In the categories section, you can set any behavior category to warning or fail. The warning will not affect the policy CI/CD status, while the fail will trigger a failing TH policy if any indicator belonging to that particular category shows up during analysis.
Restrict behavior category
policies 
{
    profile "repository_profile" 
    {
        inherit_rules "sdlc_default"
  
        processing
        {        
            filter
            {
                enabled   true
                
                matches   "file"
                pattern   "*"
                
                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly target specific behavior categories"

                hunting
                {
                    categories
                    {
                        network   fail
                        evasion   warning
                    }
                } 
            }
        }
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes​

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

This action may take a long time if the entire package store needs to be synchronized.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-project/my-package@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the rl-secure output or the SAFE report (rl-html) for details on restricted behaviors.

Check the CLI output​

Use the find command to see whether the expected TH policies were triggered. The output should confirm that the policy violations are detected in the package store for which the configuration was modified.

rl-secure find --term=TH1510? --purl=pkg:rl/my-project/my-package

The output should be similar to the following example. It indicates the policies triggered due to the configuration change and shows the details on the restricted behaviors. 

--------------------------------------------------------------------------------
[ MATCHED ] my-project/my-package@1.0
[ TH15101 ] [ L5:PASS ] <P1> / [M] Severity [H] Effort / (x4)
            Detected presence of files with behaviors that were marked to issue 
            a warning.
Root Cause ---------------------------------------------------------------------
            [ BH12805 ] Detects presence of debuggers.
Violations ---------------------------------------------------------------------
     1) test/node_modules/node-notifier/vendor/notifu/notifu.exe
     2) test/node_modules/node-notifier/vendor/notifu/notifu64.exe
     3) test/node_modules/node-notifier/vendor/snoreToast/snoretoast-x64.exe
     4) test/node_modules/node-notifier/vendor/snoreToast/snoretoast-x86.exe
--------------------------------------------------------------------------------
[ MATCHED ] my-project/my-package@1.0
[ TH15102 ] [ L5:FAIL ] <P0> / [H] Severity [H] Effort / (x544)
            Detected presence of files with behaviors that were explicitly
            restricted.
Root Cause ---------------------------------------------------------------------
            [ BH12195 ] Contains references to anonymous e-mail providers.
            [ BH12205 ] Creates a UDP socket bound to an incoming connection.
            [ BH16103 ] Contains URLs related to online payment services.
            [ BH16104 ] Contains URLs that contain basic authentication
                        credentials.
            [ BH16107 ] Contains URLs that link to interesting file formats.
Violations ---------------------------------------------------------------------
     1) test/.vscode/launch.json
     2) test/README.md
     3) test/build/static/js/2.04094455.chunk.js
     4) test/build/static/js/2.04094455.chunk.js.map
     5) test/build/static/js/main.5a30b093.chunk.js

Check the SAFE report​

  • In the SAFE report, select Issues from the left sidebar and use the Add Filter button to find the relevant policies (Filter by: Issue > Operator: is one of > Value: TH15101, TH15102).
  • Expand the Info dropdown for each policy to show files with explicitly restricted behaviors.
  • Select a file you're interested in to show more information about it. Check the Issues tab on the file details page to verify that the analysis triggered the relevant policies and that the desired behaviors are restricted.

Restrict specific behaviors​

In this example, all projects in a package store exhibit some undesirable behaviors that can potentially indicate your software has been tampered with. Since only two behaviors are critical, we can restrict them by their IDs instead of affecting the whole behavior categories. We want to call attention to them by either only issuing a warning (TH15101) and triggering a failing policy (TH15102).

To do this, we're modifying the policy configuration file for the entire package store (the .repository_policy.info file). When changes are synchronized, the configuration will apply to all projects, packages and versions in the package store.

Specifically, we're creating a processing filter that will look for specific behaviors by their IDs and trigger the appropriate policies.

1. Modify package store policy settings​

1) In the rl-secure package store, navigate to the policy configuration file in the root directory and open it in a text editor. In this example, the full path to the file we're editing is /home/armando/my-repository/.repository_policy.info.

2) In the .repository_policy.info file, add the hunting section.

  • To ensure that the filter is applied when analyzing files, set enabled to true.
  • With matches set to "file" and pattern set to "*", the filter will target all files across all package versions. We're using this because behaviors are always tied to specific files.
  • In behaviors, you can include a behavior ID and set it to warning or fail. The warning will not affect the policy CI/CD status, while the fail will trigger a failing TH policy when any file in the project has a behavior with this identifier.
Restrict specific behavior
policies 
{
    profile "repository_profile" 
    {
        inherit_rules "sdlc_default"
  
        processing
        {        
            filter
            {
                enabled   true
                
                matches   "file"
                pattern   "*"
                
                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly target specific behaviors"

                hunting
                {
                    behaviors
                    {
                        BH16123   warning 
                        BH15245   fail
                    }
                } 
            }
        }
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes​

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

This action may take a long time if the entire package store needs to be synchronized.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-project/my-package@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the rl-secure output or the SAFE report (rl-html) for details on restricted behaviors.

Check the CLI output​

Use the find command to see whether the expected TH policies were triggered. The output should confirm that the policy violations are detected in the package store for which the configuration was modified.

rl-secure find --term=TH1510? --purl=pkg:rl/my-project/my-package

The output should be similar to the following example. It indicates the policies triggered due to the configuration change and shows the details about the restricted behaviors.

--------------------------------------------------------------------------------
[ MATCHED ] my-project/my-package@1.0
[ TH15101 ] [ L5:PASS ] <P1> / [M] Severity [H] Effort / (x134)
            Detected presence of files with behaviors that were marked to issue 
            a warning.
Root Cause ---------------------------------------------------------------------
            [ BH16123 ] Contains URLs related to URL shortener services.
Violations ---------------------------------------------------------------------
     1) test/build/static/js/2.04094455.chunk.js
     2) test/build/static/js/2.04094455.chunk.js.map
     3) test/build/static/js/main.5a30b093.chunk.js.map
     4) test/node_modules/.cache/babel-loader/0f31bc6f7dc3969686da789e45bbadbe.json
     5) test/node_modules/.cache/babel-loader/2525e45fe9857d022008568d4cd456f2.json
--------------------------------------------------------------------------------
[ MATCHED ] my-project/my-package@1.0
[ TH15102 ] [ L5:FAIL ] <P0> / [H] Severity [H] Effort / (x1)
            Detected presence of files with behaviors that were explicitly
            restricted.
Root Cause ---------------------------------------------------------------------
            [ BH15245 ] Calculates the SHA-512 hash of data.
Violations ---------------------------------------------------------------------
     1) test/node_modules/fs-write-stream-atomic/index.js

Check the SAFE report​

  • In the SAFE report, select Issues from the left sidebar and use the Add Filter button to find the relevant policies (Filter by: Issue > Operator: is one of > Value: TH15101, TH15102).
  • Expand the Info dropdown for each policy to show files with explicitly restricted behaviors.
  • Select a file you're interested in to show more information about it. Check the Issues tab on the file details page to verify that the analysis triggered the relevant policies and that the desired behaviors are restricted.