Home

Complete Guide: All Possible Ways to Use secagent

This page gives practical usage patterns for local development, Docker, CI pipelines, baseline adoption, suppressions, report generation, and troubleshooting.

0) Pull Official Images from Docker Hub

# secagent tool image
docker pull sikanderali/secagent:latest

Test pulled secagent image

docker run --rm sikanderali/secagent:latest version

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v "$(pwd)":/workspace -w /workspace \
  sikanderali/secagent:latest \
  scan --target /workspace --config /workspace/secagent.yml.example

0.1) One-Command Local Installer (No Docker)

This command clones the repo, creates virtualenv, installs secagent, and verifies it automatically.

bash <(curl -fsSL https://raw.githubusercontent.com/SIKANDERKUMBHAR/secagent-devsecops-orchestrator/main/scripts/setup-local.sh)

Installer also sets up scanner binaries/wrappers (Semgrep, Checkov, Gitleaks, Trivy), creates a global launcher at ~/.local/bin/secagent, and updates shell profile PATH.

1) Quick Start (Local Python)

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

secagent validate-config --config secagent.yml
secagent scan --target . --config secagent.yml

2) Quick Start (Docker)

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v "$(pwd)":/workspace -w /workspace \
  sikanderali/secagent:latest scan --target /workspace --config /workspace/secagent.yml

3) Main Commands

secagent scan --target . --config secagent.yml
Run all enabled scanners and evaluate policy.

secagent validate-config --config secagent.yml
Validate config before CI runs.

secagent doctor --config secagent.yml
Verify local scanner dependencies and versions.

secagent baseline create --input-json reports/secagent-report.json
Create baseline from current findings.

secagent report --input-json reports/secagent-report.json --output-html reports/custom.html
Re-render HTML from JSON report.

4) Output Formats

Configure in YAML:

report:
  formats: [json, html, sarif, md]

5) Baseline Adoption Mode

Best for teams with existing technical debt.

# first run
secagent scan --target . --config secagent.yml
secagent baseline create --input-json reports/secagent-report.json --output .secagent-baseline.json

# next runs (fail only on new findings when policy enabled)
secagent scan --target . --config secagent.yml --baseline .secagent-baseline.json

6) Suppressions (Governed Exceptions)

suppressions:
  - fingerprint: "abc123"
    reason: "False positive in test fixture"
    expires: "2026-12-31"
    tools: ["semgrep"]
  - rule_id: "CKV_DOCKER_2"
    path_glob: "examples/**"
    reason: "Example-only Dockerfile"
    expires: "2026-06-30"

Expired suppressions are rejected by default unless configured warn-only.

7) Policy Control for CI

policy:
  fail_on_severities: [CRITICAL, HIGH]
  max_allowed:
    MEDIUM: 10
    LOW: 999
  fail_on_secrets: true
  fail_on_new_only: true

Stable exit codes:

8) Scan a Git Repository URL

# public repository
secagent scan --target https://github.com/org/repo.git --config secagent.yml

# private repository using env token name
export GITHUB_TOKEN=***
secagent scan --target https://github.com/org/private-repo.git \
  --token-env GITHUB_TOKEN --ref main --config secagent.yml

9) GitHub Actions Pattern

- run: secagent scan --target . --config secagent.yml
- uses: actions/upload-artifact@v4
  with:
    name: secagent-reports
    path: reports/
- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: reports/secagent-report.sarif

10) Troubleshooting

11) Example End-to-End Flow

# 1. validate
secagent validate-config --config secagent.yml

# 2. initial scan
secagent scan --target . --config secagent.yml

# 3. create baseline
secagent baseline create --input-json reports/secagent-report.json --output .secagent-baseline.json

# 4. enforce new findings only
secagent scan --target . --config secagent.yml --baseline .secagent-baseline.json