Secret Scan action

Last updated: Oct 26, 2026

The SS action detects hardcoded secrets and credentials (API keys, passwords, tokens, and similar sensitive data) in your repository.

If you want, you can attribute the runs to your Fluid Attacks group. For the setup, read Authentication.

Marketplace: fluidattacks/ss-action

Scan modes

The action uses differential scanning each time that a base commit is available. It uses a full scan only when there is nothing to compare with. The action detects the default branch automatically with git remote show origin. Thus, all branch names (such as main, master, trunk and develop) work without configuration.

The two differential modes compare with a known base commit, not only the previous commit. Thus, the action analyzes all the changes in a push with many commits. This keeps CI fast and makes sure that the action does not miss changes.

Setup

1. Create the workflow

Add .github/workflows/secret-scan.yml to your repository:

name: SECRET_SCAN
on:
  push:
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
    - cron: "0 8 * * 1" # optional: weekly full scan every Monday at 8am

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # required: full history enables differential scanning

      - uses: fluidattacks/ss-action@<version> # Use latest released version
        id: scan

      # Optional: upload findings to the GitHub Security tab
      - name: Upload results to GitHub Security tab
        if: always()
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: ${{ steps.scan.outputs.sarif_file }}

• fetch-depth: 0 downloads the full git history. The differential scan must have this history to find the base commit and to detect the default branch with git remote show origin. You can omit it only if you force scanner_mode: full.
• upload-sarif is optional. If you use it, run it with if: always(). Thus, the step uploads the results each time, also when the action finds secrets.
• The optional schedule trigger adds a weekly full scan. This scan finds secrets that were present before you added this workflow.

Without a configuration file, the action scans the full repository and writes the results to .fluidattacks-secret-scan-results.sarif.

2. (Optional) Add a configuration file

To customize scan paths or output format, create a YAML configuration file in a location that you select in your repository. Then, give its path to the action with scan_config_path:

- uses: fluidattacks/ss-action@<version>
  id: scan
  with:
    scan_config_path: .github/secret-scan-config.yaml

The path is relative to the repository root. If the file does not exist at that path, the job fails immediately.

3. Push and run

Commit the workflow file and push. The scan runs automatically.

Configuration

When you give scan_config_path, the action uses only that file. If you do not give it, the action uses the built-in default values: it scans the full repository and writes the results to .fluidattacks-secret-scan-results.sarif.

This action uses only the ss and output keys.

ss:
  include:
    - . # paths to scan (default: entire repo)
  exclude:
    - tests/ # paths to skip

output:
  file_path: .fluidattacks-secret-scan-results.sarif
  format: SARIF

ss.include

A list of paths (files or directories) to scan.

• Full scan: uses this list. If the list is not set, the default value is . (full repository).
• Differential scan: always uses the list of changed files, for all values of this setting.

ss.exclude

A list of paths to exclude from the scan. It applies in the full and differential modes.

output

Action inputs

Forcing a full scan

Use scanner_mode: full to scan the full repository on each run, for all triggers. This is useful for scheduled audits:

- uses: fluidattacks/ss-action@main
  id: scan
  with:
    scanner_mode: full

Action outputs

You can use these outputs in the subsequent workflow steps:

- name: Comment on PR
  if: steps.scan.outputs.vulnerabilities_found == 'true'
  run: echo "Secrets detected — check the Security tab."

Viewing results

After the workflow runs, the findings appear in two places:

1. GitHub Security tab — Go to your repository → Security → Code scanning alerts. Each finding shows severity, file location, and the exact line where the secret was detected.
2. Pull request annotations — On pull requests, findings appear as inline annotations directly in the code diff.

Common scenarios

Scan only specific folders (monorepo)

ss:
  include:
    - services/api/
    - services/web/
  exclude:
    - services/legacy/

Export results as CSV

For common scenarios and troubleshooting, read GitHub Actions.

Troubleshooting

The action doesn't detect my default branch: The action runs git remote show origin to detect the default branch. For this command, the checkout step must have fetch-depth: 0, so that the remote metadata is available. If the detection fails, make sure that the origin remote is configured correctly.

For common scenarios and troubleshooting, read GitHub Actions.

Prerequisites

• A GitHub repository (public or private).
• GitHub Actions enabled on the repository.
• A Linux (x86_64 or aarch64) or macOS (Apple Silicon) runner — the action installs the ss binary, which does not work on Windows or Intel Mac.