Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DevDonzo/warden/llms.txt

Use this file to discover all available pages before exploring further.

Warden integrates with GitHub Actions through a generated workflow file that runs a full security scan on every push and pull request. The workflow enforces configurable severity gates—if the scan finds vulnerabilities at or above the threshold you set, the pipeline exits with a non-zero code and the job fails. This keeps security policy machine-enforced rather than advisory, without requiring any manual review step before a gate decision is made.

​
Generating the workflow

The warden bootstrap-ci command writes a ready-to-use GitHub Actions workflow file into your repository’s .github/workflows/ directory. You do not need to author the YAML by hand. 
warden bootstrap-ci --scanner npm-audit --severity high
The generated workflow file is written to .github/workflows/warden.yml by default. Commit this file to your repository to activate the pipeline.

​
Flag reference

FlagTypeDefaultDescription
--workflow-name <name>stringwarden.ymlFilename for the generated workflow inside .github/workflows/.
--scanner <type>snyk | npm-audit | allnpm-auditScanner to invoke in CI. Use snyk for deeper vulnerability intelligence or npm-audit for zero-credential audits.
--severity <level>low | medium | high | criticalhighMinimum severity that triggers a gate failure. Findings below this level are reported but do not fail the job.
--create-configflag—Create a default .wardenrc.json alongside the workflow if one does not already exist.
--forceflag—Overwrite the workflow file (and config, if --create-config is set) even if they already exist on disk.

​
The generated workflow

Running warden bootstrap-ci --scanner npm-audit --severity high produces the following workflow. Review it and commit it as-is or adapt it to your needs. 
name: Warden Security Patrol

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'
  workflow_dispatch:

jobs:
  warden:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install project dependencies
        run: |
          if [ -f package-lock.json ]; then
            npm ci
          elif [ -f package.json ]; then
            npm install
          else
            echo "No package.json found; skipping dependency install"
          fi

      - name: Run Warden
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
        run: >
          npx @devdonzo/warden scan .
          --ci
          --json
          --scanner npm-audit
          --severity high

      - name: Upload Warden artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: warden-artifacts
          path: |
            scan-results
            SECURITY-ADVISORY.md
The --ci flag activates policy gate enforcement, meaning Warden will exit with a non-zero code when a severity threshold or posture limit is crossed. Without --ci, the scan runs and produces output but the job always exits 0. The --json flag suppresses the interactive banner and emits structured JSON, which is suitable for downstream steps that parse scan output.

​
Exit codes

Warden uses distinct exit codes in CI mode so that your pipeline can distinguish between a genuine tool failure and a deliberate policy gate:
Exit codeMeaning
0Scan completed and all policy gates passed.
1Fatal error—the environment was misconfigured, a required tool was missing, or an unexpected exception occurred.
2Policy gate triggered—one or more findings met or exceeded the configured severity threshold or posture limit.
A job step that exits 2 means security policy said “stop”; a job step that exits 1 means something broke. Both cause the GitHub Actions job to fail, but they point you in different directions when diagnosing.

​
Setting up the pipeline

1

Install Warden and generate the workflow

Run the bootstrap command from the root of your repository:
warden bootstrap-ci --scanner npm-audit --severity high
Warden creates .github/workflows/warden.yml. If you also want a starter config file, append --create-config.
2

Add repository secrets

Open your repository’s Settings → Secrets and variables → Actions page and add the following secrets:
  • SNYK_TOKEN — Required when using --scanner snyk or --scanner all. Obtain a token from app.snyk.io.
  • GITHUB_TOKEN — Automatically provided by GitHub Actions. You do not need to create it, but the workflow’s permissions block must grant pull-requests: write if Warden opens PRs.
The auto-generated GITHUB_TOKEN only has pull-requests: write permission if you explicitly declare it in the workflow’s permissions block, as shown in the example above. Without it, any step that attempts to open a pull request will fail with a 403 error.
3

Commit and push the workflow

git add .github/workflows/warden.yml
git commit -m "ci: add Warden security patrol workflow"
git push
GitHub Actions picks up the new workflow file on the next push or pull request targeting main.
4

Verify the first run

Navigate to the Actions tab in your repository. The Warden Security Patrol workflow should appear and run. Scan artifacts—including scan-results/scan-results.json and SECURITY-ADVISORY.md—are uploaded as a build artifact named warden-artifacts after every run, whether the job passes or fails.

​
Adding baseline checks

Baseline checks extend the basic scan step by comparing current findings against a committed snapshot of previously accepted risk. This catches regressions—new or worsened findings—without failing on issues you have already triaged. Add the following step after the Run Warden step in your workflow: 
- name: Baseline check
  run: warden baseline --check --severity high
The step reads scan-results/scan-results.json (written by the preceding scan step) and compares it against .warden-baseline.json in your repository root. If new or worsened findings above high severity are found, the step exits 2 and the job fails. See Baseline Management for full details on creating and maintaining baseline files.

​
Dry-run mode in CI

To run Warden on pull requests without enforcing gates—for example, to post informational comments without blocking a merge—add the --dry-run flag: 
- name: Run Warden (dry run)
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
  run: >
    npx @devdonzo/warden scan .
    --ci
    --dry-run
    --json
    --scanner npm-audit
    --severity high
In dry-run mode Warden scans, produces reports, and evaluates policy—but it does not create branches or open pull requests, and it does not exit 2 on a gate violation. This is useful for draft PRs or repositories where you want visibility before enabling hard enforcement.

Build docs developers (and LLMs) love

Get started for freeTalk to us