sec-report-kit

Generate HTML vulnerability reports from multiple security tools (SAST, SCA, IaC, and secrets) with a CLI and MCP server.

Release history: see CHANGELOG.md.

Supported source types:

• trivy
• pip-audit
• safety
• bandit
• gitleaks
• semgrep
• codeql (SARIF)
• osv-scanner
• checkov
• tfsec
• trufflehog (JSON or NDJSON)
• cyclonedx (CycloneDX SBOM component inventory, e.g. *.cdx.json)

Install

pip install -e .

With MCP support:

pip install -e .[mcp]

CLI Usage

Both commands are available:

• srk
• sec-report-kit

Render Trivy JSON:

srk render trivy --input security_reports/trivy-image-report-v1.0.21.json --output security_reports/report-trivy.html --source trivy --target shankonduru/cpkc-poc:v1.0.21

Render a CycloneDX SBOM into an HTML component inventory:

srk render sbom --input security_reports/frontend.cdx.json --output security_reports/report-sbom.html --source cyclonedx --target frontend

Unlike the vulnerability reports, render sbom produces a component inventory (name, version, type, ecosystem, language, license, package URL) with type/ecosystem/license breakdowns rather than severity-based findings.

Render pip-audit JSON:

srk render pip-audit --input pip-audit.json --output security_reports/report-pip-audit.html --source pip-audit --target requirements.txt

Render Safety JSON:

srk render safety --input security_reports/safety.json --output security_reports/report-safety.html --source safety --target requirements.txt

Render a consolidated HTML report from all supported scanner files in a directory:

srk render consolidated --input security_reports --output security_reports --source consolidated --target sec-report-kit

This command writes consolidated-security-report.html to the output folder. If --output is omitted, it defaults to the same folder passed to --input. The consolidated renderer reads raw JSON/SARIF inputs, generates the per-tool HTML reports automatically, and then links/embeds those generated HTML files in the dashboard. You do not need to pre-render individual HTML reports first.

The top of the consolidated report is an analytics dashboard:

• Donut charts of findings by severity and by scan category (dependencies, code, secrets, IaC)
• The share of dependency findings that list a fixed version
• Stacked bar charts, split by severity, of findings per tool, the top 10 vulnerable dependencies, and the top 10 code (SAST) rules

Charts are inline SVG/HTML with no external libraries, so the report still opens offline. Hover or keyboard focus shows exact values, and every bar chart has a "View as table" option. Dependencies are counted as distinct advisories from the scanner that reports the most, because Trivy, pip-audit and Safety name the same CVE with different IDs.

Example with implicit output folder:

srk render consolidated --input security_reports --source consolidated --target sec-report-kit

All render commands accept both --source and --target so callers can control the header values shown as Source: and Target: in generated HTML.

Helper Scripts (bat/sh)

Cross-platform helper scripts are available in scripts/.

When render helpers are called without an explicit <target_name>, they automatically use the repository root folder name as the report target label. If <source_name> is omitted, each helper uses its tool name (for example trivy, gitleaks, consolidated).

Install this package and Python-installable scanners:

# Linux/macOS
bash scripts/install_tools.sh

# Windows
scripts\install_tools.bat

After cloning on a new machine, run the install script above to recreate the local .tools/ directory and install required external CLI binaries (codeql, tfsec, gitleaks, trufflehog, osv-scanner) alongside Python dependencies. The .tools/ folder is intentionally not committed to git.

Install or update external CLI binaries directly:

python scripts/install_external_clis.py --repo-root .

Default behavior skips tools that are already installed locally.

Force re-download/reinstall for all supported external tools:

python scripts/install_external_clis.py --repo-root . --force

Install only selected tool(s) with --tool (can be repeated or comma-separated):

python scripts/install_external_clis.py --repo-root . --tool osv-scanner
python scripts/install_external_clis.py --repo-root . --tool tfsec --tool gitleaks --force
python scripts/install_external_clis.py --repo-root . --tool tfsec,gitleaks

Supported --tool values: codeql, tfsec, gitleaks, trufflehog, osv-scanner. For convenience, ocs-scanner is accepted as an alias for osv-scanner.

Run all unit tests locally with coverage:

# Linux/macOS (optional arg: <coverage_dir>)
bash scripts/run_unit_tests_with_coverage.sh
bash scripts/run_unit_tests_with_coverage.sh htmlcov

# Windows (optional arg: <coverage_dir>)
scripts\run_unit_tests_with_coverage.bat
scripts\run_unit_tests_with_coverage.bat htmlcov

Run pip-audit and write JSON output:

# Linux/macOS (optional args: <report_dir> <requirements_file>)
bash scripts/run_pip_audit.sh
bash scripts/run_pip_audit.sh reports requirements.txt

# Windows (optional args: <report_dir> <requirements_file>)
scripts\run_pip_audit.bat
scripts\run_pip_audit.bat reports requirements.txt

Run Safety CLI and write JSON output:

# Linux/macOS (optional args: <report_dir> <requirements_file>)
bash scripts/run_safety.sh
bash scripts/run_safety.sh security_reports requirements.txt

# Windows (optional args: <report_dir> <requirements_file>)
scripts\run_safety.bat
scripts\run_safety.bat security_reports requirements.txt

Offline / local DB support: Safety CLI requires network access by default. To enable offline scanning, download the vulnerability DB while online and cache it locally:

</code></pre>
</blockquote>
<p>When render helpers are called without an explicit <code><target_name></code>, they automatically use the repository root folder name as the report target label. If <code><source_name></code> is omitted, each helper uses its tool name (for example <code>trivy</code>, <code>gitleaks</code>, <code>consolidated</code>).</p>
<blockquote>
<p>bash scripts/download_safety_db.sh</p>
<h1 id="user-content-windows">Windows<a href="#user-content-windows" aria-label="Link to heading 'Windows'" data-heading-content="Windows" class="anchor"></a></h1>
<p>scripts\download_safety_db.bat</p>
<pre><code>
```bash
# Corporate/proxy environments with self-signed certificates
bash scripts/download_safety_db.sh .tools/safety-db --no-verify-ssl
scripts\download_safety_db.bat .tools\safety-db --no-verify-ssl

The DB is saved to .tools/safety-db/. Both run_safety.sh and run_safety.bat automatically detect and use it on subsequent runs, skipping the network call. Re-run the download script periodically to refresh the DB with the latest vulnerabilities.

Run Bandit and write JSON output:

# Linux/macOS (optional args: <report_dir> <target_path>)
bash scripts/run_bandit.sh
bash scripts/run_bandit.sh security_reports src

# Windows (optional args: <report_dir> <target_path>)
scripts\run_bandit.bat
scripts\run_bandit.bat security_reports src

Convert pip-audit JSON report to HTML:

# Linux/macOS (optional args: <report_dir> <target_name> <source_name>)
bash scripts/render_pip_audit_html.sh
bash scripts/render_pip_audit_html.sh reports requirements.txt
bash scripts/render_pip_audit_html.sh reports requirements.txt sbom-scan

# Windows (optional args: <report_dir> <target_name> <source_name>)
scripts\render_pip_audit_html.bat
scripts\render_pip_audit_html.bat reports requirements.txt
scripts\render_pip_audit_html.bat reports requirements.txt sbom-scan

Convert Safety JSON report to HTML:

# Linux/macOS (optional args: <report_dir> <target_name> <source_name>)
bash scripts/render_safety_html.sh
bash scripts/render_safety_html.sh security_reports requirements.txt
bash scripts/render_safety_html.sh security_reports requirements.txt safety-db

# Windows (optional args: <report_dir> <target_name> <source_name>)
scripts\render_safety_html.bat
scripts\render_safety_html.bat security_reports requirements.txt
scripts\render_safety_html.bat security_reports requirements.txt safety-db

These render helpers generate the HTML file and open it automatically in your default browser.

Convert sample Trivy JSON report to HTML:

# Linux/macOS (optional args: <report_dir> <target_name> <source_name>)
bash scripts/render_trivy_html.sh
bash scripts/render_trivy_html.sh security_reports my-image
bash scripts/render_trivy_html.sh security_reports my-image image-scan

# Windows (optional args: <report_dir> <target_name> <source_name>)
scripts\render_trivy_html.bat
scripts\render_trivy_html.bat security_reports my-image
scripts\render_trivy_html.bat security_reports my-image image-scan

Convert all supported scanner reports in a folder to one consolidated HTML report:

# Linux/macOS (optional args: <report_dir> <target_name> [source_name])
bash scripts/render_consolidated_html.sh
bash scripts/render_consolidated_html.sh security_reports sec-report-kit
bash scripts/render_consolidated_html.sh security_reports sec-report-kit consolidated-dashboard

# Windows (optional args: <report_dir> <target_name> [source_name])
scripts\render_consolidated_html.bat
scripts\render_consolidated_html.bat security_reports sec-report-kit
scripts\render_consolidated_html.bat security_reports sec-report-kit consolidated-dashboard

For consolidated scripts, when the 3rd argument starts with --, it is treated as an extra CLI option (for backward compatibility with existing --modified-since usage).

You can also restrict which report files are picked up by modification time and cap how many of the newest files are included:

# Only files modified today
bash scripts/render_consolidated_html.sh security_reports sec-report-kit --modified-since today
scripts\render_consolidated_html.bat security_reports sec-report-kit --modified-since today

# Since yesterday
bash scripts/render_consolidated_html.sh security_reports sec-report-kit --modified-since yesterday
scripts\render_consolidated_html.bat security_reports sec-report-kit --modified-since yesterday

# Last 7 days
bash scripts/render_consolidated_html.sh security_reports sec-report-kit --modified-since last-7-days
scripts\render_consolidated_html.bat security_reports sec-report-kit --modified-since last-7-days

# Since a fixed date and only the 10 newest matching files
bash scripts/render_consolidated_html.sh security_reports sec-report-kit --modified-since 2026-05-01 --limit 10
scripts\render_consolidated_html.bat security_reports sec-report-kit --modified-since 2026-05-01 --limit 10

# Between two dates
bash scripts/render_consolidated_html.sh security_reports sec-report-kit --modified-since 2026-05-01 --modified-until 2026-05-10
scripts\render_consolidated_html.bat security_reports sec-report-kit --modified-since 2026-05-01 --modified-until 2026-05-10

# From a fixed date until today
bash scripts/render_consolidated_html.sh security_reports sec-report-kit --modified-since 2026-05-01
scripts\render_consolidated_html.bat security_reports sec-report-kit --modified-since 2026-05-01

--modified-since accepts ISO dates/datetimes plus today, yesterday, last-week, and last-7-days. --modified-until accepts ISO dates/datetimes plus today and yesterday. Use --modified-since by itself for "from date until now", or combine both options for a bounded date range. When --limit is used, the newest matching files are selected first.

Convert sample Bandit JSON report to HTML:

# Linux/macOS (optional args: <report_dir> <target_name> <source_name>)
bash scripts/render_bandit_html.sh
bash scripts/render_bandit_html.sh security_reports my-python-project
bash scripts/render_bandit_html.sh security_reports my-python-project python-sast

# Windows (optional args: <report_dir> <target_name> <source_name>)
scripts\render_bandit_html.bat
scripts\render_bandit_html.bat security_reports my-python-project
scripts\render_bandit_html.bat security_reports my-python-project python-sast

Convert sample Gitleaks JSON report to HTML:

# Linux/macOS (optional args: <report_dir> <target_name> <source_name>)
bash scripts/render_gitleaks_html.sh
bash scripts/render_gitleaks_html.sh security_reports my-repository
bash scripts/render_gitleaks_html.sh security_reports my-repository secret-scan

# Windows (optional args: <report_dir> <target_name> <source_name>)
scripts\render_gitleaks_html.bat
scripts\render_gitleaks_html.bat security_reports my-repository
scripts\render_gitleaks_html.bat security_reports my-repository secret-scan

By default, JSON is written to reports/pip-audit.json and HTML to reports/pip-audit-report.html.

Additional Tool Workflows

Script Coverage Matrix

The table below reflects what is currently implemented in scripts/:

Bandit End-To-End Example

Generate JSON first, then render HTML:

# Linux/macOS
bash scripts/run_bandit.sh security_reports src
bash scripts/render_bandit_html.sh security_reports my-python-project

# Windows
scripts\run_bandit.bat security_reports src
scripts\render_bandit_html.bat security_reports my-python-project

Other Run Script Usage

# Linux/macOS
bash scripts/run_trivy.sh security_reports alpine:latest
bash scripts/run_safety.sh security_reports requirements.txt
bash scripts/run_gitleaks.sh security_reports .
bash scripts/run_semgrep.sh security_reports .
bash scripts/run_codeql.sh security_reports codeql-db codeql/python-queries
bash scripts/run_osv_scanner.sh security_reports .
bash scripts/run_checkov.sh security_reports .
bash scripts/run_tfsec.sh security_reports .
bash scripts/run_trufflehog.sh security_reports .

# Windows
scripts\run_trivy.bat security_reports alpine:latest
scripts\run_safety.bat security_reports requirements.txt
scripts\run_gitleaks.bat security_reports .
scripts\run_semgrep.bat security_reports .
scripts\run_codeql.bat security_reports codeql-db codeql/python-queries
scripts\run_osv_scanner.bat security_reports .
scripts\run_checkov.bat security_reports .
scripts\run_tfsec.bat security_reports .
scripts\run_trufflehog.bat security_reports .

Trivy and Gitleaks End-To-End

Generate JSON and then render HTML using wrapper scripts:

# Linux/macOS
bash scripts/run_trivy.sh security_reports your-image:tag
bash scripts/render_trivy_html.sh security_reports your-image:tag

bash scripts/run_gitleaks.sh security_reports .
bash scripts/render_gitleaks_html.sh security_reports my-repository

# Windows
scripts\run_trivy.bat security_reports your-image:tag
scripts\render_trivy_html.bat security_reports your-image:tag

scripts\run_gitleaks.bat security_reports .
scripts\render_gitleaks_html.bat security_reports my-repository

Manual CLI render examples:

srk render semgrep --input security_reports/semgrep.json --output security_reports/semgrep-report.html --source semgrep --target my-repo
srk render codeql --input security_reports/codeql.sarif.json --output security_reports/codeql-report.html --source codeql --target my-repo
srk render osv-scanner --input security_reports/osv-scanner.json --output security_reports/osv-scanner-report.html --source osv-scanner --target requirements.txt
srk render safety --input security_reports/safety.json --output security_reports/safety-report.html --source safety --target requirements.txt
srk render checkov --input security_reports/checkov.json --output security_reports/checkov-report.html --source checkov --target terraform
srk render tfsec --input security_reports/tfsec.json --output security_reports/tfsec-report.html --source tfsec --target terraform
srk render trufflehog --input security_reports/trufflehog.json --output security_reports/trufflehog-report.html --source trufflehog --target my-repo
srk render bandit --input security_reports/bandit.json --output security_reports/bandit-report.html --source bandit --target my-python-project
srk render gitleaks --input security_reports/gitleaks.json --output security_reports/gitleaks-report.html --source gitleaks --target my-repository
srk render trivy --input security_reports/trivy-image-report-v1.0.21.json --output security_reports/trivy-report.html --source trivy --target my-image

MCP Server

Run MCP server over stdio:

srk mcp serve --transport stdio

Available MCP Tools

The vulnerability tools (summarize_json, render_report_from_json, validate_input) accept source_type ("trivy", "pip-audit", "safety", "bandit", "gitleaks", "semgrep", "codeql", "osv-scanner", "checkov", "tfsec", "trufflehog", or "auto") and input_path (absolute path to JSON file).

The SBOM tools (summarize_sbom, render_sbom_from_json) accept source_type ("cyclonedx" or "auto") and input_path. render_sbom_from_json also takes output_path, target, and an optional source label.

VS Code (GitHub Copilot Agent / MCP extension)

Add to your VS Code settings.json (or .vscode/mcp.json in the workspace):

{
  "mcp": {
    "servers": {
      "sec-report-kit": {
        "type": "stdio",
        "command": "srk",
        "args": ["mcp", "serve", "--transport", "stdio"]
      }
    }
  }
}

Note: If srk is not on the system PATH, replace "command" with the full path to the executable, e.g. "C:/Users/you/.venv/Scripts/srk.exe".

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "sec-report-kit": {
      "command": "srk",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

Cursor

Open Cursor Settings → MCP and add a new server entry:

{
  "sec-report-kit": {
    "command": "srk",
    "args": ["mcp", "serve", "--transport", "stdio"]
  }
}

Or add it to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "sec-report-kit": {
      "command": "srk",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

Windsurf (Codeium)

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sec-report-kit": {
      "command": "srk",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

Using a virtual environment

If the package is installed in a .venv, use the full path to avoid PATH issues:

Windows:

{
  "command": "C:/MyProjects/sec-report-kit/.venv/Scripts/srk.exe",
  "args": ["mcp", "serve", "--transport", "stdio"]
}

macOS / Linux:

{
  "command": "/home/user/sec-report-kit/.venv/bin/srk",
  "args": ["mcp", "serve", "--transport", "stdio"]
}

Package Publish

Build:

python -m build

Upload to TestPyPI:

python -m twine upload --repository testpypi dist/*

Upload to PyPI:

python -m twine upload dist/*