> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# studion/security

A suite of security tools, e.g. check dependencies for vulnerabilities, scan for secrets leaks, and more. Tailored for use within Studion pipelines.


## Commands

### analyze_code

Run static analysis, or SAST, to find vulnerabilities in the codebase. Utilizes the Semgrep "scan" command to do the analysis. For details on usage see https://semgrep.dev/docs/cli-reference.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base_branch` | string |  | The name of the base branch for this scan. Commonly a long-lived branch, e.g. "main" or "master".
 |
| `full_scan` | boolean | false | The flag indicating whether to scan the entire codebase vs just files changed from the last commit, or the whole branch if it is a short-lived branch, i.e. pull request.
 |
| `root_dir` | string | . | The root of the codebase to analyze. Defaults to . (working directory). Complements the full scan mode, by enabling partial scan of the codebase.
 |
| `rules` | string | p/default p/owasp-top-ten p/r2c-security-audit p/cwe-top-25 p/eslint | The space-separated list of Semgrep rules, e.g. YAML configuration file, URL of the configuration file, or Semgrep registry entry name.
 |
| `verbose` | boolean | false | The flag indicates whether to show more details about rules, files, etc. |

### assess_image

Scan Docker images for vulnerabilities and secrets. Vulnerability scan is performed by Grype (https://github.com/anchore/grype) while scanning for secrets is executed by Trivy (https://github.com/aquasecurity/trivy). It is possible to provide additional configurable options by following the Grype (https://github.com/anchore/grype?tab=readme-ov-file#configuration) and Trivy (https://trivy.dev/latest/docs/configuration/) guides, respectively. However, some options cannot be overridden, such as source and format, since they are passed as command line arguments and thus have the highest precedence.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `exclude` | string |  | Space delimited list of GLOB expressions specifying files and paths to exclude from the vulnerability scan. The secrets scan is not affected by this.
 |
| `ignore_fix_status` | string |  | Comma delimited list of matches to ignore based on the vulnerability fix status. Available options - 'fixed', 'not-fixed', 'wont-fix', 'unknown'.
 |
| `image` | string |  | The Docker image to scan. Support following schemes (1) 'repo-name/image-name:tag' (2) '/path/to/image.tar'. Bases on provided scheme it will either use local Docker daemon or tarball archive from disk as a source. Performs environment variable substitution before using the value of this parameter.
 |
| `out_vuln_path` | string | /tmp/security-orb/output/image-findings.sarif | Path to the file to write the vulnerability report to. |
| `scanners` | string | vuln secret | Space delimited list of scans to run against the image. By default, runs all available scans. Following is available (1) 'vuln' - vulnerability scan (2) 'secret' - secrets scan of the image and its configuration.
 |
| `severity` | enum | high | Choose a severity level to fail on with the error code. By default, when severity level of 'high' or greater is detected the command will fail with exit code 2.
 |

### detect_secrets

Scan for secrets inside a directory, or Git repository. The heavy lifting is done by Gitleaks, for details see https://github.com/gitleaks/gitleaks#gitleaks.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base_branch` | string |  | The name of the base branch for this scan. Commonly a long-lived branch, e.g. "main" or "master".
 |
| `base_revision` | string |  | The hash of the last scanned commit from the prior build. Usually, pass CircleCI "<<pipeline.git.base_revision>>" pipeline parameter.
 |
| `baseline_report` | string |  | The path to the baseline report, i.e. issues that can be ignored. |
| `config` | string |  | The path to the Gitleaks config file. By default, it tries to load "<<parameters.path>>/.gitleaks.toml".
 |
| `mode` | enum | git | The scan mode describes the source path - directory or Git repository. |
| `source` | string | . | The path to the source for the scanning. Defaults to . (working directory). Only utilized in the "dir" mode. The "git" mode will always use the working directory.
 |

### generate_sbom

Generate Software Bill of Materials (SBOM) from Docker image. All the work is done by Syft, for details see https://github.com/anchore/syft?tab=readme-ov-file#getting-started. It is possible to provide additional configurable values by following this guide https://github.com/anchore/syft/wiki/configuration#config-file. However some options cannot be overridden, such as output and source since they are passed as command line arguments and thus have the highest precedence.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `exclude` | string |  | Space delimited list of GLOB expressions specifying files and paths to exclude from the source.
 |
| `format` | enum | cyclonedx-json | Choose the output format of generated SBOM. By default a JSON report conforming to the CycloneDX specification.
 |
| `image` | string |  | The Docker image to generate SBOM from. Support following schemes (1) repo-name/image-name:tag (2) /path/to/image.tar. Bases on provided scheme it will either use local Docker daemon or tarball archive from disk as a source. Performs environment variable substitution before using the value of this parameter.
 |
| `out_path` | string | /tmp/security-orb/output/sbom.json | Path to the file to write the SBOM report to. |

### install_gitleaks

Install Gitleaks (https://github.com/gitleaks/gitleaks) a tool for detecting secrets.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Choose the specific version of Gitleaks from https://github.com/anchore/grype/releases. By default, the latest version is picked.
 |

### install_grype

Install Grype (https://github.com/anchore/grype) a vulnerability scanner for container images and filesystems.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Choose the specific version of Grype from https://github.com/anchore/grype/releases. By default, the latest version is picked.
 |

### install_semgrep

Install Semgrep (https://github.com/semgrep/semgrep) a fast open-source static analysis tool. Requires the runtime environment with Python 3 and Pip. Installs Semgrep in the user-specific location, not system-wide.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Choose the specific version of Semgrep from https://github.com/semgrep/semgrep/releases. By default, the latest version is picked.
 |

### install_syft

Install Syft (https://github.com/anchore/syft) a CLI tool for generating a Software Bill of Materials (SBOM) from container images and filesystems.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Choose the specific version of Syft from https://github.com/anchore/syft/releases. By default, the latest version is picked.
 |

### install_trivy

Install Trivy (https://github.com/aquasecurity/trivy) all-in-one open source security scanner, optionally selecting the specific version.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Choose the specific version of Trivy from https://github.com/aquasecurity/trivy/releases. By default, the latest version is picked.
 |

### scan_dependencies

By default, scan production dependencies for critical and high severity vulnerabilities. Uses the "audit" command of the targeted package manager.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `pkg_json_dir` | string | . | Path to the directory containing "package.json" file. Not needed when "package.json" is in the root.
 |
| `pkg_manager` | string | ${DEFAULT_PKG_MANAGER} | Choose Node.js package manager to use. Supports npm and pnpm.
The package manager must follow the format <name>[@<version|tag>].
Omitting the version implies that the npm version is determined by the target Node.js environment,
while pnpm will default to the latest version.
 |
| `scan_command` | string |  | Custom command to scan dependencies for vulnerabilities. Useful when default commands, "npm audit --audit-level=high --omit=dev" or "pnpm audit --audit-level high --prod", are unsuitable.
 |

### scan_dockerfile

By default, scan a Dockerfile for high and critical severity misconfigurations. Underneath the Trivy (https://github.com/aquasecurity/trivy) does the scanning.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `dockerfile_dir` | string | . | The path to the directory containing the Dockerfile. Defaults to . (working directory).
 |
| `severity` | string | HIGH,CRITICAL | Comma delimited list of misconfiguration severity levels to scan for. Supported levels, in order from least to most critical - UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL. By default, scans for HIGH and CRITICAL severity levels.
 |

## Jobs

### analyze_code_diff

Run a diff-aware scan on the codebase and report findings.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base_branch` | string |  | The name of the base branch for this scan. Commonly a long-lived branch, e.g. "main" or "master".
 |
| `rules` | string | p/default p/owasp-top-ten p/r2c-security-audit p/eslint | The space-separated list of Semgrep rules, e.g. YAML configuration file, URL of the configuration file, or Semgrep registry entry name.
 |
| `verbose` | boolean | false | The flag indicates whether to show more details about rules, files, etc. |

### analyze_code_full

Run a full scan on the codebase and report findings.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `root_dir` | string | . | The root of the codebase to analyze. Defaults to . (working directory).
 |
| `rules` | string | p/default p/owasp-top-ten p/r2c-security-audit p/eslint | The space-separated list of Semgrep rules, e.g. YAML configuration file, URL of the configuration file, or Semgrep registry entry name.
 |
| `verbose` | boolean | false | The flag indicates whether to show more details about rules, files, etc. |

### detect_secrets_dir

Detect secrets leak inside a project at the directory level.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `baseline_report` | string |  | The path to the baseline report, i.e. issues that can be ignored. |
| `config` | string |  | The path to the Gitleaks config file. By default, it tries to load "<<parameters.path>>/.gitleaks.toml".
 |
| `source` | string | . | The path to the directory to scan. Defaults to . (working directory). |

### detect_secrets_git

Detect secrets leak inside a project at the repository level.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base_branch` | string |  | The name of the base branch for this scan. Commonly a long-lived branch, e.g. "main" or "master".
 |
| `base_revision` | string |  | The hash of the last scanned commit from the prior build. Usually, pass CircleCI "<<pipeline.git.base_revision>>" pipeline parameter.
 |
| `baseline_report` | string |  | The path to the baseline report, i.e. issues that can be ignored. |
| `config` | string |  | The path to the Gitleaks config file. By default, it tries to load "<<parameters.path>>/.gitleaks.toml".
 |

## Executors

### node

Docker executor integrating a suite of security tools for vulnerability detection within CircleCI Node.js pipelines.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Choose the executor resource class |
| `tag` | string | lts | Choose a specific studiondev/node-security image tag: https://hub.docker.com/r/studiondev/node-security/tags
 |

## Examples

### dockerfile_misconfigurations

By default, the "scan_dockerfile" command checks if a Dockerfile, in the working directory,
has high or critical severty misconfigurations.
There is an option to specify a different directory with Dockerfile for a scan.


```yaml
version: '2.1'
orbs:
  security: studion/security@x.y.z
jobs:
  scan_app_dockerfile:
    executor: security/node
    steps:
      - security/scan_dockerfile:
          dockerfile_dir: ~/app
workflows:
  misconfigurations:
    jobs:
      - scan_app_dockerfile
```

### git_detect_leaks

The "detect_secrets_git" job checks for secrets leak inside a Git repository.
When a current branch is not a base branch it scans all commits inside the current branch.
If the current branch and base branch are the same it scans commits from base revision
up to last commit in a build.
The base revision should be provided for the most accurate results, while the base branch
can be overridden if necessary.


```yaml
version: '2.1'
orbs:
  security: studion/security@x.y.z
workflows:
  detect_app_leaks:
    jobs:
      - security/detect_secrets_git:
          base_revision: <<pipeline.git.base_revision>>
```

### image_sbom

The "generate_sbom" command generates SBOM from the Docker image.
By default, the Docker daemon is used as a source. This can be changed
to use the Docker archive from the disk by providing the path to the tarball
file as the "image".
There is an option to customize output path of the report, exclude
directories or files from the scan with glob expressions or use
different output format.


```yaml
version: '2.1'
orbs:
  security: studion/security@x.y.z
jobs:
  sbom:
    environment:
      TARGET_IMAGE: studiondev/node-security:lts
    executor: security/node
    steps:
      - checkout
      - security/generate_sbom:
          exclude: /etc /home/**/*.json
          format: github-json
          image: ${TARGET_IMAGE}
          out_path: /tmp/reports/lts-sbom.json
workflows:
  compliance:
    jobs:
      - sbom
```

### image_scan

By default, the "assess_image" command scans images for high and critical
severity vulnerabilities and secrets. It uses the Docker daemon as the
image source, or alternatively an image tarball file from disk if provided.
There is an option to choose scanners, set severity levels, ignore findings
based on fix status, exclude directories or files using the glob expressions,
select different report format, and customize report path.


```yaml
version: '2.1'
orbs:
  security: studion/security@x.y.z
jobs:
  vuln-and-secrets:
    environment:
      TARGET_IMAGE: studiondev/node-security:lts
    machine:
      image: ubuntu-2404:current
    steps:
      - checkout
      - security/assess_image:
          exclude: /usr /var/**/*.log
          ignore-fix-status: not-fixed,wont-fix
          image: ${TARGET_IMAGE}
          report-path: /tmp/reports/lts-vuln.json
          severity: medium
workflows:
  scan-image:
    jobs:
      - vuln-and-secrets
```

### pnpm_scan

By default, the "scan_dependencies" command checks for production dependencies
with critical and high severity vulnerabilities.
There is an option to override the scan command, package manager, and root directory.


```yaml
version: '2.1'
orbs:
  security: studion/security@x.y.z
jobs:
  scan_command:
    executor: core/node
    steps:
      - checkout
      - security/scan_dependencies:
          pkg_json_dir: ~/app
          scan_command: pnpm audit
workflows:
  scan_app_dependencies:
    jobs:
      - scan_command
```

### sast

The "analyze_code_diff" job runs a static analysis tool to scan the codebase for vulnerabilities.
A diff-aware scanning is performed meaning only file changes in the last commit are scanned,
or files scoped to the pull request if a short-lived branch is in question.
There is an option to change a base branch and enforce a different set of scan rules.


```yaml
version: '2.1'
orbs:
  security: studion/security@x.y.z
workflows:
  test_codebase:
    jobs:
      - security/analyze_code_diff:
          base_branch: prod
          rules: p/comment p/secure-defaults
```