Secret Scan action
Last updated: Nov 11, 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
By default, the action runs a full scan: it analyzes the full repository on each run, for all triggers.
To scan only the changed files, set scanner_mode: diff.
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.
In differential mode, the base depends on the trigger:
| Trigger | Mode | Base for comparison |
|---|---|---|
| Pull request | Differential scan | PR base branch |
| Push to the default branch | Differential scan | Commit before the push (github.event.before) |
| Push to any other branch | Differential scan | Default branch |
| Any other event (scheduled, manual, ...) | Full scan | — |
The 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. If no base commit is available (for example, on the first push of a new branch), the action runs a full scan.
Note: In differential mode, if no files changed, the action skips the
scan, sets the skip output to true, and does not produce an output file.
This is expected behavior, not an error.
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 only for differential scanning
- uses: fluidattacks/ss-action@<version> # Use latest released version
id: scan
with:
scanner_mode: diff # optional: scan only the changed files
# 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 }}Note: Replace <version> with the latest release tag. Find it on the Marketplace
page.
fetch-depth: 0downloads the full git history. The differential scan must have this history to find the base commit and to detect the default branch withgit remote show origin. You can omit it in the defaultfullmode.upload-sarifis optional. If you use it, run it withif: always(). Thus, the step uploads the results each time, also when the action finds secrets.- The optional
scheduletrigger adds a weekly full scan. This scan finds secrets that were present before you added this workflow.
Warning: Uploading to the Security tab requires GitHub Advanced Security. See GitHub Advanced Security for details.
Without a configuration file, the action scans the full repository and writes the results
to .fluidattacks-ss-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.yamlThe 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-ss-results.sarif.
This action uses only the ss, output, strict, and strictness_threshold keys.
strict: false
strictness_threshold: high # optional: low, medium, high, or critical
ss:
include:
- . # paths to scan (default: entire repo)
exclude:
- tests/ # paths to skip
output:
file_path: .fluidattacks-ss-results.sarif
format: SARIFss.include
A list of paths (files or directories) to scan.
- Full scan: uses this list. If you do not set the list, 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.
strict and strictness_threshold
Control whether the scan breaks the build. The action inputs of the same name override them. For more information, read Strict mode.
output
| Field | Default | Description |
|---|---|---|
file_path | .fluidattacks-ss-results.sarif | Path to the results file |
format | SARIF | Output format (SARIF or CSV) |
Action inputs
| Input | Required | Default | Description |
|---|---|---|---|
scan_config_path | No | — | Path to the YAML configuration file, relative to the repository root. When omitted, built-in defaults are used. The job fails if the file does not exist. |
scanner_mode | No | full | Scan mode. full scans the full repository (default). diff scans only the files changed relative to the base branch or PR base. |
strict | No | — | true or false. Set it to true to break the build when the scan finds vulnerabilities. It overrides strict in your configuration file. If you omit it, the configuration file decides. For more information, read Strict mode. |
strictness_threshold | No | — | low, medium, high, or critical. Breaks the build only for vulnerabilities at or above this severity. It overrides strictness_threshold in your configuration file. If you omit it, the configuration file decides. For more information, read Strict mode. |
group | No | — | Your Fluid Attacks group. The action gives it to the scanner as --group. For a short-lived OIDC token, the workflow must have the id-token: write permission, and the group must have a trust for the repository. If you give neither this input nor api_token, or the action gets no credentials (for example, in a pull request from a fork), the scan runs without authentication. |
api_token | No | — | Long-lived Group token for workflows that cannot use OIDC. Give it from a secret, for example ${{ secrets.FA_API_TOKEN }}. If you give this input, the action uses it and not OIDC. The token identifies the group, so you do not need the group input. |
Running a differential scan
Use scanner_mode: diff to scan only the files that changed relative to the base.
Set fetch-depth: 0 in the checkout step, so that the git history is available.
For events other than push and pull_request (for example, schedule), the action runs a full scan:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: fluidattacks/ss-action@<version>
id: scan
with:
scanner_mode: diffAction outputs
| Output | Description |
|---|---|
skip | true when the scan was skipped because a diff run found no changed files, false otherwise |
sarif_file | SARIF results file. Set when format is SARIF, ALL, or path ends in .sarif |
vulnerabilities_found | true if the scan found secrets at or above the threshold that applies, false otherwise |
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:
- 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.
- 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 does not 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
ssbinary, which does not work on Windows or Intel Mac.