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 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.

More specifically, policy configuration lets you restrict:

  • entire behavior categories. 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. If you restrict a whole behavior category, you can still allow specific behaviors from that category in the policy configuration.

  • specific behaviors by their IDs. 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.

  • specific behaviors by their label (description text). To target one or more behaviors by the contents of their description text, you can specify a string from the description text in the policy configuration. Wildcard matching is supported. All behaviors have descriptions listed in the reference documentation.

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 filters use the following policy configuration objects and their fields:

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

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 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.

Override behavior category restrictions

If you restrict an entire behavior category like in this example, you can still allow specific behaviors from that category as needed. To do that, specify the behaviors by their ID and set them to pass.

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 a new processing filter.

  • 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 hunting.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 a new processing filter.

  • 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 hunting.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.

Target behaviors by description​

In this example, we have previously restricted the entire steal behavior category for the package store by modifying the .repository_policy.info file.

However, one of our projects is a trusted application that has some of the behaviors from the restricted category. We want to allow those behaviors only in that project while keeping the category restricted for the rest of the package store.

To do this, we're going to override the behavior category restriction on the project level by modifying the .project_policy.info file. Specifically, we're creating a processing filter that will look for specific behaviors by their description text. Behaviors that match the description text from our filter will be allowed, and will not trigger a failing policy (TH15102).

1. Modify project policy settings​

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

2) In the .project_policy.info file, add a new processing filter.

  • 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 in the project. We're using this because behaviors are always tied to specific files.
  • In hunting.indicators, specify the behavior description text as a key and set its value to pass. You can use wildcard characters to create a pattern for the description text. All behaviors with descriptions that match the pattern will be allowed, and will not trigger a failing policy.

In this example, we're targeting behavior descriptions that contain the string "clipboard" anywhere in the text. This will allow behaviors like BH13350 (Accesses clipboard) from the steal category, which would otherwise be restricted by package store policy configuration.

Allow behaviors with specified description text
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
                {
                    indicators
                    {
                        "*clipboard*"   pass 
                    }
                } 
            }
        }
    }
}

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 SAFE report (rl-html) for details on restricted behaviors.

  • In the SAFE report, select Behaviors from the left sidebar. Use the filters at the top of the page to find behaviors in the steal category that contain "clipboard" in the description text.

  • Expand the Info dropdown for one of the behaviors to show components that exhibit the behavior. Select a file in the list of components to show more information about it.

  • Check the Issues tab on the file details page to verify that the allowed behaviors are not in the "Caused by" list for the TH15102 policy.