Built-in Reporters

ASH includes 15 built-in reporters that generate scan results in various formats to support different use cases, from human-readable reports to machine-processable data formats for CI/CD integration.

For detailed visual diagrams of the built-in reporter architecture and workflows, see Built-in Reporter Diagrams.

Reporter Overview

Reporter	Name	Format	Enabled by default	Use Case	Key Features
CSV Reporter	csv	CSV	Yes	Data analysis, spreadsheets	Tabular data, easy filtering
CycloneDX Reporter	cyclonedx	JSON/XML	Yes	SBOM compliance	Software Bill of Materials
Flat JSON Reporter	flat-json	JSON	Yes	Simple data processing	Flattened structure
GitHub GHAS Reporter	github-ghas	SARIF	Yes	GitHub Advanced Security	Optimized SARIF with proper severity mapping
GitLab CycloneDX Reporter	gitlab-cyclonedx	JSON	Yes	GitLab dependency scanning	CycloneDX SBOM in GitLab's report format
GitLab SAST Reporter	gitlab-sast	JSON	Yes	GitLab Security Dashboard	GitLab CI/CD integration
HTML Reporter	html	HTML	Yes	Interactive reports	Web-based, searchable
JUnit XML Reporter	junitxml	XML	Yes	CI/CD test results	Test framework integration
Markdown Reporter	markdown	Markdown	Yes	Documentation, README	Human-readable, version control friendly
OCSF Reporter	ocsf	JSON	Yes	Security data lakes	Open Cybersecurity Schema Framework
SARIF Reporter	sarif	JSON	Yes	IDE integration, CI/CD	Static Analysis Results Interchange Format
SPDX Reporter	spdx	JSON	No	License compliance	Software Package Data Exchange
Text Reporter	text	Plain text	Yes	Console output, logs	Simple, lightweight
Unused suppressions Reporter	unused-suppressions	JSON	Yes	Suppression hygiene	Lists configured suppressions that matched no finding
YAML Reporter	yaml	YAML	No	Configuration-style output	Human-readable structured data

Reporter Details

CSV Reporter

Purpose: Exports findings in comma-separated values format for spreadsheet analysis.

Configuration:

reporters:
  csv:
    enabled: true
    # The CSV reporter exposes no options. Suppressed findings are filtered by
    # global_settings.suppressions, not per reporter.

Output Structure: - Scanner name - File path - Line number - Severity level - Rule ID - Description - Suppression status

Use Cases: - Data analysis in Excel/Google Sheets - Custom reporting dashboards - Bulk finding management

---

CycloneDX Reporter

Purpose: Generates Software Bill of Materials (SBOM) in CycloneDX format.

Configuration:

reporters:
  cyclonedx:
    enabled: true
    # The CycloneDX reporter exposes no options.

Key Features: - Component inventory - Dependency relationships - Vulnerability mappings - License information - Supply chain transparency

Use Cases: - Software supply chain security - Compliance reporting - Vulnerability management - License tracking

---

Flat JSON Reporter

Purpose: Simplified JSON format with flattened structure for easy processing.

Configuration:

reporters:
  flat-json:              # Note the hyphen; 'flatjson' is not a reporter name
    enabled: true
    options:
      include_metadata: true
      include_scanner_metrics: true
      include_summary_metrics: true

Output Structure:

{
  "findings": [
    {
      "scanner": "bandit",
      "file": "src/app.py",
      "line": 42,
      "severity": "HIGH",
      "rule_id": "B602",
      "message": "subprocess call with shell=True",
      "suppressed": false
    }
  ]
}

Use Cases: - Simple data processing scripts - Custom integrations - Lightweight parsing

---

GitLab SAST Reporter

Purpose: Generates reports in GitLab Security Dashboard format for seamless CI/CD integration.

Configuration:

reporters:
  gitlab-sast:            # Note the hyphen; 'gitlab_sast' is read the same, but the linter flags it
    enabled: true
    options:
      exclude_suppressed: false

Output Structure: - GitLab SAST report format - Vulnerability details with locations - Severity mapping to GitLab standards - Scanner metadata and timestamps

Use Cases: - GitLab CI/CD pipeline integration - GitLab Security Dashboard visualization - Compliance with GitLab security workflows

Integration Example:

# .gitlab-ci.yml
security_scan:
  stage: test
  script:
    - ash . --reporters gitlab-sast
  artifacts:
    reports:
      sast: output/gl-sast-report.json

---

GitHub GHAS Reporter

Purpose: Produces a streamlined SARIF report optimized for GitHub Advanced Security (Code Scanning).

The standard SARIF reporter outputs a faithful representation of scanner results, but GitHub Code Scanning requires specific fields to display severity correctly. Without properties["security-severity"] on rules, GitHub falls back to showing raw SARIF levels ("Error"/"Warning"/"Note") instead of security severity (Critical/High/Medium/Low).

This reporter solves that by:

1. Ensuring every rule has properties["security-severity"] — preserving scanner-provided values when present, or deriving from defaultConfiguration.level / result.level when missing
2. Flattening rules from tool.extensions[] into tool.driver.rules for reliable rule resolution
3. Stripping verbose fields to significantly reduce file size (~80% smaller than the standard SARIF)
4. Excluding suppressed findings by default (GitHub has its own dismissal workflow)

Configuration:

reporters:
  github-ghas:
    enabled: true
    options:
      exclude_suppressed: true  # Exclude ASH-suppressed findings (default: true)

Output File: reports/ash.ghas.sarif

Severity Mapping (when security-severity is not provided by the scanner):

SARIF Level	security-severity	GitHub displays as
error	8.0	High
warning	6.0	Medium
note	3.0	Low
none	1.0	Low

When a scanner already provides security-severity (e.g., Grype with CVSS scores), that value is preserved as-is.

Use Cases: - GitHub Advanced Security Code Scanning - GitHub Security tab integration - Pull request security annotations - Repository security overview

Integration Example:

# .github/workflows/ash-security-scan.yml
name: ASH Security Scan

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install ASH
        run: pip install git+https://github.com/awslabs/automated-security-helper.git
      - name: Run ASH scan
        run: ash --mode local --no-fail-on-findings
      - name: Upload GHAS SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: .ash/ash_output/reports/ash.ghas.sarif
          category: ash-security-scan

---

HTML Reporter

Purpose: Interactive web-based report with search and filtering capabilities.

Configuration:

reporters:
  html:
    enabled: true
    # The HTML reporter exposes no options.

Key Features: - Interactive filtering and search - Severity-based color coding - Expandable finding details - Summary statistics - Responsive design

Use Cases: - Security team reviews - Executive reporting - Developer feedback - Audit documentation

---

JUnit XML Reporter

Purpose: Formats results as JUnit XML for CI/CD test result integration.

Configuration:

reporters:
  junitxml:
    enabled: true
    options:
      respect_severity_threshold: true

Key Features: - Test framework compatibility - CI/CD integration - Pass/fail status per scanner - Detailed failure messages

Use Cases: - Jenkins test results - GitLab CI test reporting - GitHub Actions test summaries - Build pipeline gates

---

Markdown Reporter

Purpose: Human-readable report in Markdown format for documentation.

Configuration:

reporters:
  markdown:
    enabled: true
    options:
      include_summary: true
      include_findings_table: true
      include_detailed_findings: true
      max_detailed_findings: 50
      use_collapsible_details: true
      compact: false
      top_hotspots_limit: 10

Key Features: - GitHub/GitLab compatible - Table of contents - Code syntax highlighting - Collapsible sections

Use Cases: - README security sections - Pull request comments - Documentation sites - Security runbooks

---

OCSF Reporter

Purpose: Outputs findings in Open Cybersecurity Schema Framework format.

Configuration:

reporters:
  ocsf:
    enabled: true
    # The OCSF reporter exposes no options.

Key Features: - Standardized security data format - Cloud-native security tools integration - Rich metadata support - Event correlation capabilities

Use Cases: - Security data lakes - SIEM integration - Security analytics platforms - Compliance reporting

---

SARIF Reporter

Purpose: Static Analysis Results Interchange Format for tool interoperability.

Configuration:

reporters:
  sarif:
    enabled: true
    # The SARIF reporter exposes no options.

Key Features: - IDE integration (VS Code, IntelliJ) - GitHub Security tab integration - Rich metadata and locations - Tool interoperability

Use Cases: - IDE security annotations - GitHub Advanced Security - Security tool chains - Compliance reporting

---

SPDX Reporter

Purpose: Software Package Data Exchange format for license compliance.

Configuration:

reporters:
  spdx:
    enabled: true
    # The SPDX reporter exposes no options.

Key Features: - SPDX 2.3 JSON, built from the same CycloneDX SBOM as the cyclonedx reporter - Declared licenses, when the SBOM gives an SPDX license ID or expression - Package versions and purl external references - DESCRIBES and CONTAINS relationships from the scanned project to each package

Package-level only: there are no file entries, and download location, concluded license and copyright text are NOASSERTION.

Use Cases: - License compliance - Open source governance - Legal review processes - Supply chain transparency

---

Text Reporter

Purpose: Simple plain text output for console display and logging.

Configuration:

reporters:
  text:
    enabled: true
    options:
      include_summary: true
      include_findings_table: true
      include_detailed_findings: true
      max_detailed_findings: 50
      top_hotspots_limit: 10

Key Features: - Console-friendly output - Color-coded severity levels - Compact summary format - Configurable verbosity

Use Cases: - Command-line usage - Log file output - Simple CI/CD notifications - Quick security overviews

---

YAML Reporter

Purpose: Structured YAML output for configuration-style data representation.

Configuration:

reporters:
  yaml:
    enabled: true
    # The YAML reporter exposes no options.

Key Features: - Human-readable structure - Configuration file compatibility - Hierarchical data organization - Comment support

Use Cases: - Configuration-based workflows - Infrastructure as Code integration - Human-readable data exchange - Custom processing pipelines

---

GitLab CycloneDX Reporter

Purpose: Emits the CycloneDX SBOM in the artifact shape GitLab's dependency scanning consumes.

Distinct from the plain CycloneDX Reporter: the payload is the same SBOM, but the file is named for GitLab's dependency_scanning report artifact so a pipeline can hand it straight to GitLab.

Configuration:

reporters:
  gitlab-cyclonedx:       # Note the hyphens
    enabled: true

Output file: reports/ash.gl-dependency-scanning-report.cdx.json

Use Cases: - GitLab dependency scanning - GitLab Security Dashboard dependency view

Integration Example:

# .gitlab-ci.yml
security_scan:
  stage: test
  script:
    - ash . --reporters gitlab-cyclonedx
  artifacts:
    reports:
      dependency_scanning: .ash/ash_output/reports/ash.gl-dependency-scanning-report.cdx.json

---

Unused Suppressions Reporter

Purpose: Lists the suppression rules in your configuration that matched no finding during the scan.

A suppression that stops matching is invisible without this report: the finding it used to hide may have been fixed, or the rule may have been written against a path or rule ID that no longer exists. Either way the rule is now dead configuration, and a dead suppression is a rule nobody is reviewing.

This reporter is enabled by default, so every scan writes it.

Configuration:

reporters:
  unused-suppressions:    # Note the hyphen
    enabled: true

Output file: reports/ash.unused-suppressions.json

Use Cases: - Suppression hygiene reviews - Pruning suppressions after a fix lands - Catching suppressions written against a stale rule ID or path

Multi-Reporter Usage

Common Combinations

# Development workflow
ash --reporters text,html,sarif

# CI/CD pipeline
ash --reporters sarif,junitxml,gitlab-sast

# Compliance reporting
ash --reporters spdx,cyclonedx,ocsf

# Executive reporting
ash --reporters html,markdown,csv

Configuration Example

reporters:
  # Quick feedback
  text:
    enabled: true
    options:
      include_summary: true
      include_detailed_findings: false

  # Detailed analysis
  html:
    enabled: true

  # CI/CD integration
  sarif:
    enabled: true

  # Data processing
  csv:
    enabled: true

Best Practices

Reporter Selection

Choose reporters based on your audience and use case:

# For developers
reporters: [text, sarif, html]

# For security teams
reporters: [html, csv, ocsf]

# For compliance
reporters: [spdx, cyclonedx, markdown]

# For CI/CD
reporters: [sarif, junitxml, gitlab-sast]

Performance Considerations

# Optimize for speed. The HTML and CSV reporters expose no options, so the lever
# is which reporters run at all rather than how each one behaves.
reporters:
  html:
    enabled: false          # Skip the largest artifact

  csv:
    enabled: true

Output Organization

# Organize outputs by type
ash --output-dir results/ \
  --reporters sarif,html,csv \
  --output-format "{reporter}/{timestamp}"

Integration Examples

GitHub Actions

- name: Security Scan
  run: ash --reporters sarif,text

- name: Upload SARIF to GitHub Advanced Security
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: .ash/ash_output/reports/ash.ghas.sarif
    category: ash-security-scan

GitLab CI

security_scan:
  script:
    - ash --reporters gitlab-sast,text
  artifacts:
    reports:
      sast: results/gitlab-sast/results.json

Jenkins

pipeline {
  stages {
    stage('Security Scan') {
      steps {
        sh 'ash --reporters junitxml,html'
        publishTestResults testResultsPattern: 'results/junitxml/*.xml'
        publishHTML([
          allowMissing: false,
          alwaysLinkToLastBuild: true,
          keepAll: true,
          reportDir: 'results/html',
          reportFiles: 'index.html',
          reportName: 'Security Report'
        ])
      }
    }
  }
}

Troubleshooting

Common Issues

Large report files:

reporters:
  markdown:                 # html has no options; markdown is the one that caps detail
    options:
      max_detailed_findings: 100

Encoding issues:

reporters:
  csv:
    enabled: true           # The CSV reporter exposes no options

CI/CD integration failures:

# Validate output format
ash --reporters sarif --validate-output

Next Steps

• Scanner Configuration: Configure security scanners
• Suppressions: Manage false positives
• CI/CD Integration: Automate security scanning