Skip to main content

Report Filtering and Customization Guide

This guide covers advanced features for filtering, customizing, and configuring Kestrel reports to meet specific organizational needs.

Table of Contents​

  1. Report Filtering
  2. HTML Customization
  3. Configuration Options
  4. Custom Rules
  5. Output Formats
  6. Advanced Examples

Report Filtering​

Severity Filtering​

Filter findings by severity level to focus on critical issues:

# Show only critical and high severity findings
kestrel scan --path . --min-severity high --html --output critical-issues.html

# Show only critical findings
kestrel scan --path . --min-severity critical --json --output critical.json

# Include all findings (default)
kestrel scan --path . --min-severity info --html --output complete-report.html

Framework Filtering​

Select specific compliance frameworks:

# Single framework
kestrel scan --path . --frameworks fips_140_3 --html --output fips-report.html

# Multiple frameworks
kestrel scan --path . --frameworks fips_140_3,pci_dss_4 --html --output compliance-report.html

# All available frameworks (default)
kestrel scan --path . --html --output full-compliance.html

File Type Filtering​

Focus on specific programming languages:

# Go files only
kestrel scan --path . --include "*.go" --html --output go-security.html

# Python files only
kestrel scan --path . --include "*.py" --html --output python-security.html

# Multiple file types
kestrel scan --path . --include "*.go,*.py,*.js" --html --output multi-lang.html

# Exclude test files
kestrel scan --path . --exclude "*_test.go,*test*.py" --html --output production-only.html

Rule Filtering​

Include or exclude specific security rules:

# Include only specific rules
kestrel scan --path . --include-rules "weak-crypto,insecure-random" --html --output specific-rules.html

# Exclude specific rules
kestrel scan --path . --exclude-rules "deprecated-api" --html --output filtered-rules.html

# Use custom rule configuration
kestrel scan --path . --rules-config custom-rules.yaml --html --output custom-report.html

HTML Customization​

Theme Configuration​

Choose from predefined themes or create custom ones:

# Light theme (default)
kestrel scan --path . --html --html-theme light --output light-report.html

# Dark theme
kestrel scan --path . --html --html-theme dark --output dark-report.html

# Corporate theme
kestrel scan --path . --html --html-theme corporate --output corp-report.html

# Custom theme with CSS file
kestrel scan --path . --html --html-theme custom --html-css custom-theme.css --output branded-report.html

Chart Configuration​

Control chart types and data visualization:

# Enable all charts (default when --html-charts is used)
kestrel scan --path . --html --html-charts --output charts-report.html

# Specific chart types
kestrel scan --path . --html --html-charts "severity,compliance,trends" --output selected-charts.html

# Disable charts for minimal report
kestrel scan --path . --html --output minimal-report.html

# Custom chart colors
kestrel scan --path . --html --html-charts --html-chart-colors "critical:#e74c3c,high:#f39c12,medium:#f1c40f,low:#2ecc71" --output colored-charts.html

Report Metadata​

Customize report headers and metadata:

# Add custom title and description
kestrel scan --path . --html \
  --report-title "MyProject Security Audit" \
  --report-description "Quarterly cryptographic compliance review" \
  --report-version "Q1-2024" \
  --output quarterly-report.html

# Add custom logo and branding
kestrel scan --path . --html \
  --report-logo "https://company.com/logo.png" \
  --report-footer "© 2024 Company Security Team" \
  --output branded-report.html

Configuration Options​

Configuration File​

Create a configuration file for consistent settings:

kestrel.yaml

# Global configuration
global:
  verbose: true
  quiet: false
  
# Scanning configuration
scan:
  frameworks:
    - fips_140_3
    - pci_dss_4
  min_severity: medium
  include_patterns:
    - "*.go"
    - "*.py"
    - "*.js"
    - "*.java"
  exclude_patterns:
    - "*_test.go"
    - "test_*.py"
    - "vendor/*"
    - "node_modules/*"
    
# Semgrep configuration
semgrep:
  timeout: 300
  max_memory: "2GB"
  rules:
    - "rules/semgrep/crypto.yml"
    - "p/security-audit"
    
# HTML reporting
html:
  theme: "corporate"
  enable_charts: true
  chart_types:
    - "severity"
    - "compliance"
    - "trends"
    - "languages"
  custom_css: "styles/security-theme.css"
  
# Report metadata
report:
  title: "Security Compliance Report"
  description: "Automated cryptographic security audit"
  company: "ACME Corporation"
  logo: "assets/logo.png"
  
# Policy enforcement
policy:
  fail_on_critical: true
  fail_on_high: false
  max_high_violations: 10
  max_medium_violations: 50

Use the configuration file:

# Use config file
kestrel scan --config kestrel.yaml --path . --html --output configured-report.html

# Override specific options
kestrel scan --config kestrel.yaml --path . --html-theme dark --output dark-configured.html

Environment Variables​

Configure using environment variables:

# Set environment variables
export KESTREL_FRAMEWORKS="fips_140_3,pci_dss_4"
export KESTREL_MIN_SEVERITY="high"
export KESTREL_HTML_THEME="dark"
export KESTREL_FAIL_ON_CRITICAL="true"
export KESTREL_REPORT_TITLE="Production Security Audit"

# Run with environment configuration
kestrel scan --path . --html --output env-configured.html

Custom Rules​

Creating Custom Rules​

Define organization-specific security rules:

custom-crypto-rules.yaml

# Custom cryptographic security rules
rules:
  - id: company-weak-encryption
    name: "Company Prohibited Weak Encryption"
    description: "Detects use of encryption algorithms prohibited by company policy"
    severity: critical
    frameworks:
      - company_policy
    patterns:
      - pattern: "DES("
        language: "*"
        message: "DES encryption is prohibited by company policy"
      - pattern: "RC4("
        language: "*"
        message: "RC4 encryption is prohibited by company policy"
        
  - id: company-key-length
    name: "Company Minimum Key Length Policy"
    description: "Enforces minimum key lengths per company policy"
    severity: high
    frameworks:
      - company_policy
    patterns:
      - pattern: "RSA.*1024"
        language: "*"
        message: "RSA keys must be at least 2048 bits"
      - pattern: "AES.*128"
        language: "*"
        message: "AES keys should be 256 bits for sensitive data"
        
  - id: company-random-source
    name: "Company Approved Random Sources"
    description: "Requires use of cryptographically secure random sources"
    severity: medium
    frameworks:
      - company_policy
    patterns:
      - pattern: "Math.random()"
        language: "javascript"
        message: "Use crypto.getRandomValues() for cryptographic purposes"
      - pattern: "random.random()"
        language: "python"
        message: "Use secrets module for cryptographic random values"

Custom Framework Definition​

company-policy.yaml

# Company security policy framework
framework:
  id: company_policy
  name: "ACME Corporation Security Policy"
  version: "2024.1"
  description: "Internal cryptographic security requirements"
  
requirements:
  - id: ACME-CRYPTO-001
    title: "Approved Encryption Algorithms"
    description: "Only approved encryption algorithms may be used"
    severity: critical
    rules:
      - company-weak-encryption
      
  - id: ACME-CRYPTO-002
    title: "Minimum Key Lengths"
    description: "Cryptographic keys must meet minimum length requirements"
    severity: high
    rules:
      - company-key-length
      
  - id: ACME-CRYPTO-003
    title: "Secure Random Generation"
    description: "Cryptographically secure random number generation required"
    severity: medium
    rules:
      - company-random-source

compliance_levels:
  - level: "full"
    score: 100
    requirements: ["ACME-CRYPTO-001", "ACME-CRYPTO-002", "ACME-CRYPTO-003"]
  - level: "basic"
    score: 80
    requirements: ["ACME-CRYPTO-001", "ACME-CRYPTO-002"]

Using Custom Rules​

# Load custom rules and framework
kestrel scan --path . \
  --rules-config custom-crypto-rules.yaml \
  --frameworks company_policy \
  --html --output company-compliance.html

# Combine custom and standard frameworks
kestrel scan --path . \
  --rules-config custom-crypto-rules.yaml \
  --frameworks fips_140_3,company_policy \
  --html --output comprehensive-audit.html

Output Formats​

PDF Format Options​

Generate professional PDF reports with customizable layouts:

# Basic PDF report
kestrel scan --path . --pdf --output security-report.pdf

# Customized PDF with branding
kestrel scan --path . --pdf --output quarterly-report.pdf \
  --pdf-title "Q1 2024 Security Assessment" \
  --pdf-description "Comprehensive Cryptographic Compliance Review" \
  --pdf-company "ACME Corporation Security Team"

# Landscape orientation for wide tables
kestrel scan --path . --pdf --output landscape-report.pdf \
  --pdf-orientation L \
  --pdf-page-size Letter \
  --pdf-theme corporate

# Executive summary PDF
kestrel scan --path . --pdf --output executive-summary.pdf \
  --pdf-title "Executive Security Summary" \
  --pdf-company "Board of Directors" \
  --pdf-theme professional \
  --min-severity high

PDF Configuration Options:

  • --pdf-title: Report title (default: "Security Compliance Report")
  • --pdf-description: Report description
  • --pdf-company: Organization name
  • --pdf-theme: Theme style (professional, corporate)
  • --pdf-orientation: Page orientation (P=Portrait, L=Landscape)
  • --pdf-page-size: Page size (A4, Letter, Legal)

JSON Format Options​

Customize JSON output structure:

# Detailed JSON with full context
kestrel scan --path . --json --json-detailed --output detailed.json

# Minimal JSON for API consumption
kestrel scan --path . --json --json-minimal --output minimal.json

# JSON with embedded fixes
kestrel scan --path . --json --json-include-fixes --output with-fixes.json

# Pretty-printed JSON
kestrel scan --path . --json --json-pretty --output pretty.json

SARIF Format Options​

Configure SARIF output for security platforms:

# Standard SARIF 2.1.0
kestrel scan --path . --sarif --output results.sarif

# SARIF with custom tool info
kestrel scan --path . --sarif \
  --sarif-tool-name "ACME Security Scanner" \
  --sarif-tool-version "1.0.0" \
  --output custom-tool.sarif

# SARIF with GitHub integration metadata
kestrel scan --path . --sarif --sarif-github-actions --output github.sarif

Table Format Options​

Customize console table output:

# Compact table format
kestrel scan --path . --table --table-compact

# Wide table with full details
kestrel scan --path . --table --table-wide

# CSV format for spreadsheet import
kestrel scan --path . --csv --output findings.csv

# Markdown table format
kestrel scan --path . --markdown --output findings.md

Advanced Examples​

Multi-Environment Reports​

Generate different reports for different environments:

# Development environment (all findings)
kestrel scan --path . \
  --config dev-config.yaml \
  --html --html-theme light \
  --report-title "Development Security Scan" \
  --output dev-security.html

# Staging environment (medium and above)
kestrel scan --path . \
  --config staging-config.yaml \
  --min-severity medium \
  --html --html-theme corporate \
  --report-title "Staging Security Audit" \
  --output staging-security.html

# Production environment (high and critical only)
kestrel scan --path . \
  --config prod-config.yaml \
  --min-severity high \
  --html --html-theme dark \
  --report-title "Production Security Audit" \
  --fail-on-critical \
  --output prod-security.html

Compliance Mapping​

Generate framework-specific compliance reports:

# FIPS 140-3 compliance report
kestrel scan --path . \
  --frameworks fips_140_3 \
  --html --html-charts \
  --report-title "FIPS 140-3 Compliance Report" \
  --report-description "Federal cryptographic standards compliance" \
  --output fips-compliance.html

# PCI DSS compliance report
kestrel scan --path . \
  --frameworks pci_dss_4 \
  --html --html-charts \
  --report-title "PCI DSS 4.0 Compliance Report" \
  --report-description "Payment card industry security standards" \
  --output pci-compliance.html

# Combined compliance dashboard
kestrel scan --path . \
  --frameworks fips_140_3,pci_dss_4 \
  --html --html-charts \
  --report-title "Multi-Framework Compliance Dashboard" \
  --output compliance-dashboard.html

Executive Summary Reports​

Create high-level reports for management:

# Executive summary with trends
kestrel scan --path . \
  --html --html-charts "compliance,trends" \
  --report-title "Q1 2024 Security Executive Summary" \
  --report-description "High-level cryptographic security posture" \
  --min-severity high \
  --html-theme corporate \
  --output executive-summary.html

# Board-ready compliance report
kestrel scan --path . \
  --html --html-charts "compliance" \
  --report-title "Annual Security Compliance Report" \
  --report-description "Board of Directors Security Review" \
  --report-logo "company-logo.png" \
  --html-theme corporate \
  --output board-report.html

Continuous Monitoring​

Set up automated report generation:

#!/bin/bash
# Continuous monitoring script

DATE=$(date +%Y%m%d)
TIME=$(date +%H%M)

# Daily security scan
kestrel scan --path /app \
  --config monitoring-config.yaml \
  --html --html-charts \
  --report-title "Daily Security Scan - $DATE" \
  --output reports/daily-$DATE-$TIME.html

# Weekly trend report
if [ $(date +%u) -eq 1 ]; then  # Monday
  kestrel scan --path /app \
    --html --html-charts "trends,compliance" \
    --report-title "Weekly Security Trends" \
    --output reports/weekly-$(date +%Y%U).html
fi

# Monthly compliance report
if [ $(date +%d) -eq 1 ]; then  # First of month
  kestrel scan --path /app \
    --frameworks fips_140_3,pci_dss_4 \
    --html --html-charts \
    --report-title "Monthly Compliance Report - $(date +%B\ %Y)" \
    --output reports/monthly-$(date +%Y%m).html
fi

Best Practices​

1. Report Organization​

  • Consistent Naming: Use standardized naming conventions for reports
  • Version Control: Track report configurations in version control
  • Archive Strategy: Implement retention policies for historical reports

2. Performance Optimization​

  • Incremental Scanning: Focus on changed files for large repositories
  • Parallel Processing: Use multiple workers for large codebases
  • Caching: Cache dependencies and rules for faster scans

3. Customization Guidelines​

  • Theme Consistency: Maintain consistent branding across reports
  • Rule Maintenance: Regularly review and update custom rules
  • Framework Alignment: Ensure custom frameworks align with company policies

4. Integration Patterns​

  • API Integration: Use JSON output for API-driven workflows
  • Dashboard Integration: Embed HTML reports in security dashboards
  • Alerting Integration: Connect to incident management systems

For enterprise features and advanced customization options, see the Enterprise Integration Guide.