Configuring Code Security

You can use Code Security without any configuration except in these cases:

  • Special treatment of source root - In a given repo or folder, include specific folders, exclude others.

  • Scan-time ignores - Ignore classes of files or detectors, or pieces of text at scan time (you can also perform ignores in your Code Security account).

  • Detector inclusion or exclusion - For cases where you want to disable existing detectors, or enable experimental ones.

  • Output formats - You can switch output formats to JSONClosed JavaScript Object Notation. A lightweight data interchange format., JUnit, and others, which can help outline your pipeline automation.

  • Custom detectors - Code Security can load custom detectors that you build, and you can specify its location in the configuration.

You can use spectral init to generate a base configuration.

Copy 
$ $HOME/.spectral/spectral init
            Initialized your spectral configuration in '.spectral/'.

This creates starter configuration layout in a special .spectral folder.

Copy 
$ tree .spectral
                .spectral
                ├── rules
                │   ├── merchants.speql.yaml
                │   └── sample.yaml
                └── spectral.yaml

            1 directory, 3 files

Select this folder for source control.

Configuration File

The main Code Security configuration file is spectral.yaml. It configures these parameters:

  • Input sources - Paths to scan.

  • Ignores - Items to ignore and the stage to apply ignores.

  • Reporter outputs -Reporter module to activate.

  • Detectors - Detectors to include and/or exclude

  • Metadata - Additional functionality to activate, such as masking, debug run and so on.

Copy

.spectral/spectral.yaml

# you can omit the reporter section entirely (you'll get a stylish reporter by default)
                reporter:
                outputs:
                stylish: {}         # nice looking CLI reports
                # stylish: { html: "output.html" }  # produce HTML reports
                # stylish: { csv: "output.csv" }  # produce CSV reports

                # log:              # use a logger
                #   json: true      # enable JSON logging
                #   file: out.json  # put output in a file

                # junit: {}        # Great for integrating with CI systems that understand JUnit XML (all of them, probably)
                # ignores: {}      # A reporter output that streams results as ignores

                #
                # Ignoring Matches
                #
                # you can specify ignores for matches that you know exist
                # and acknowledge them, but you don't care about them for now.
                #
                # These are regex: rule_id, rule_name, match_text, path.
                # To get a fingerprint, run `spectral fingerprint --text YOUR-SECRET`
                #
                # match_ignores:
                #     ignores:
                #     - match_text: MYSQL_ROOT_PASSWORD
                #     - rule_id: <rule id>
                #       rule_name: <rule name>
                #       match_text: <rule id>
                #       path: <path>
                #       match_fingerprint: 79cdb7f2e0e4a96520304ff641f45f230be4f362a4a16c704730115a85fa545f

                projects:
                sample:
                project:
                name: sample
                input:
                - local: .
                name: sources
                # you can add a few more. 
                # everything is relative to working directory (where you run spectral from)
                #
                # - local: nteract/node_modules
                #  name: nteract
                rules:
                roots:
                - rules      # folder(s) relative to this file
                # cherry-pick rules for these roots
                # include:
                #    tags:
                #    - node
                #    ids: []
                # exclude:
                #    tags:
                #    - node
                #    ids: []

                # add as many more projects as you like:
                # all_pythons:
            # ...

Exclude Rules by Severity

You can use the include or exclude tags. For example, if you want to see just errors, you can use the tag error in the include, or use the exclude tags warning and info which gives the same semantic.

You can use the include or exclude tags also through CLI options. For example, --include-tags error or --exclude-tags warning,info.

Ignores

You can run a scan, and choose to ignore results for known issues or issues that you prefer address later.

There are two main ways to perform ignores:

  • Glob ignores - Ignores the files completely.

  • Match ignores - Ignores the actual matches by file name, content, rule, and more.

Glob Ignores

This is similar to .gitignore file ignoring an entire folder, a glob of a file structure or a specific file, regardless of any scan.

For example, if there is a large (in GBs) tf-models file and you have reasonable certainty there no security issues.

To ignore this file, add a special .ignore file to your repo, and set its content similar to a regular .gitignore.

tf-models/*

Note - If there is .gitignore in the root of the scan, all the glob's inside the .gitignore file is ignored.

Match Ignores

This ignores the specified text, such as test keys, demo keys, and more.

You can also ignore a specific rule and a specific set of files under the rule.

For example, to ignore all credit cards showing under a test folder, specify the PCI rule. Below the rule, specify a file glob, such as tests/.*.

To add ignores, edit the main spectral configuration file:

Copy

.spectral/spectral.yaml

match_ignores:
                ignores:
                - match_text: MYSQL_ROOT_PASSWORD
                - rule_id: <rule id, regex>
                rule_name: <rule name, regex>
                match_text: <rule id, regex>
                path: <path, regex>
            match_fingerprint: b76fe610abe3bdaa92d4002dc0516dfa21c2dbf520373c6203469d0dee369888

Fingerprinting

When you want to ignore a secret, or a piece of confidential text without specify it, you can use a cryptographically secure digest fingerprinting. To fingerprint your piece of text, dd this fingerprint to your ignore rule:

Copy 
$ spectral fingerprint --text AKIAXXXXXXXXXXXXXXXX
            b76fe610abe3bdaa92d4002dc0516dfa21c2dbf520373c6203469d0dee369888

Inline Code Ignores

To provide more flexibility, we support adding ignores in your source code (as code comments) using this pattern:

spectral:ignore-[file|next-line|line] [detector|fingerprint|text] [COMMENT]

Modes

  • spectral:ignore-line - Ignore match in the same line

  • spectral:ignore-next-line - Ignore next line match

  • spectral:ignore-file - Ignore in all file

Categories (supports multiple values, comma separated):

  • detector - Ignore by specific detector id.

  • fingerprint - Ignore by specific fingerprint.

  • text - Ignore text prefix

Examples

  • Ignore match in the same line by detector:

    Copy 
    AKIAXXXXXXXXXXXXXXXX // spectral:ignore-line detector:CLD001

  • Ignore match by a fingerprint:

    To get the fingerprint, run this Bash command:

    Copy 
    $ $HOME/.spectral/spectral fingerprint --text AKIAXXXXXXXXXXXXXXXX

    To ignore the match, run:

    Copy 
    AKIAXXXXXXXXXXXXXXXX // spectral:ignore-line fingerprint:b76fe610abe3bdaa92d4002dc0516dfa21c2dbf520373c6203469d0dee369888

  • Ignore match by text prefix:

    Copy 
    AKIAXXXXXXXXXXXXXXXX // spectral:ignore-line text:AKI

  • Ignore multiple categories:

    Copy 
    AKIAXXXXXXXXXXXXXXXX // spectral:ignore-line detector:CLD001 text:AKI

  • Describe the ignore action in a comment field:

    Copy 
    AKIAXXXXXXXXXXXXXXXX // spectral:ignore-line detector:CLD001 comment:'Testing token'

  • Ignore multiple detectors in a file:

    Copy 
    // spectral:ignore-file detector:CLD001,CLD002

Ignore Rules Categorization

Categorization is designed to enhance policy compliance within organizations by providing visibility into all ignores, whether defined in the Spectral configuration YAML file or inline in the code. This feature allows categorization of ignores to ensure they are tracked appropriately, aligning with the organization's policy compliance efforts.

YAML Configuration

Example YAML configuration of match ignores:

Copy 
match_ignores:
                ignores:
                - rule_id: CLD001
                categorization:
                kind: wont-fix | false-positive
            comment: "Test secret"

Inline Configuration

Add this initial categorization for inline ignores:

Copy 
// spectral:<ignore-kind> detector:<detector> categorization:<false-positive | wont-fix> comment:<comment>

                example
            // spectral:ignore-next-line detector:CLD001 categorization:false-positive comment:'Test secret'

When Spectral detects an ignore with categorization, the issue appears in the SpectralOps dashboard. users cannot change the ignore category or comment Users cannot resolve the issue from the dashboard. The scanner manages these issues.

Hardening - Hide Local Ignores

The hardening feature allows organizations to enforce stricter controls on local ignores. For example, if an organization wants to track all issues ignored by users, they can use the hardening feature to restrict local ignores, ensuring that all ignores are categorized and visible in the dashboard. All restricted local ignores must have a categorization. Ignores without a categorization cause the scan to fail, or they drop from the scan according to the fallback mode.

Projects

You can scan each sub-folders in a folder separately. For example, monorepo folder has sub-folders, such as client, backend, and infra (Infrastructure as code).

A sample configuration for this project:

Copy 
projects:
                infra:
                project:
                name: infra             # Name of the project
                input:
                - local: ./infra        # Path of sources to include in project
                name: sources         # Name of the path
                rules:                  
                roots:                  # Rules paths on client machine - you can add paths to custom rules you created (relative to `spectral.yaml` location - `.spectral/spectral.yaml`)
                - rules                 # This is the default if not set (`.spectral/rules`)
                include: 
                ids: []             # Ids of rules you wish to include in this project
                tags:               # Tags you wish to include in this project
                - iac
                exclude:
                ids: []             # Ids of rules you wish to exclude from this project
                tags:               # Tags you wish to exclude from this project
                - audit
                client:
                project:
                name: client
                input:
                - local: ./client
                name: sources
                rules:
                include: 
                ids: []
                tags:
                - audit
                - base
                exclude: 
                ids: []
                tags:
                - iac
                server:
                project:
                name: server
                input:
                - local: ./server
                name: sources
                rules:
                include: 
                ids: []
                tags:
                - audit
                - base
                exclude: 
                ids: []
                tags:
            - iac

This triggers three scans, one scan per project defined in the configuration.

Properties

  • project - (Mandatory)

    • name - (Mandatory)

  • input (Array) - Path of sources to include in the project. Mandatory and each element should consist of:

    • local - (Mandatory) Path of resources to include in the project.

    • name - (Mandatory) Name for given path.

  • rules - Configuration regarding rules to scan in this project.

    • roots (Array) - (Optional) Rules paths on client machine. You can add paths to custom rules you created (relative to spectral.yaml location - .spectral/spectral.yaml).

    • include - Configuration about excluding rules in this projects. Mandatory if exclude was not provided.

      • tags (Array) - (Mandatory) Collection of tags to include in this project (iac, audit).

      • ids (Array) - (Mandatory) Collection of rule ids to include in this project (DB001, TFAWS110).

    • exclude - Configuration about excluding rules in this projects. Mandatory if include was not provided.

      • tags (Array) - (Mandatory) Collection of tags to exclude in this project (iac, audit).

      • ids (Array) - (Mandatory) Collection of rule ids to exclude in this project (DB001, TFAWS110).

Configuration per Asset Type

With spectral.yaml, you can set configuration for a specific asset, and only for file-based assets. For more information, see Scan Configuration.