kestrel

README

Kestrel — Fast, sharp crypto audits

Kestrel is a CLI that scans codebases for cryptographic algorithm usage and checks it against compliance frameworks (e.g., FIPS 140-3, PCI DSS 4.0). It produces actionable findings and standards-based artifacts (SARIF and CycloneDX CBOM) so you can enforce crypto policy in CI/CD.

What It Does

• Detects cryptographic algorithm usage in source code (Go AST + Semgrep)
• Flags violations against compliance frameworks (FIPS 140-3, PCI DSS 4.0)
• Generates reports in multiple formats (table, JSON, HTML, PDF, SARIF, CBOM)
• Audits existing CBOMs against the same compliance rules

Key Features

• Standards-based outputs: SARIF 2.1.0 and CycloneDX 1.6 CBOM
• Multi-language scanning: Go AST now, Semgrep for Python/JS/TS/Java/C/C++ and more
• Compliance-first: Rule-driven enforcement with clear remediation guidance
• CI/CD friendly: Easy automation and SARIF integration

Installation

From Source

git clone https://github.com/harekrishnarai/kestrel.git
cd kestrel
go build -o bin/kestrel ./cmd/kestrel

Using Go Install

go install github.com/harekrishnarai/kestrel/cmd/kestrel@latest

Quick Start

# Scan current directory
kestrel scan

# Scan a specific path
kestrel scan --path /path/to/code

# Scan with verbose output
kestrel scan --path examples/ --verbose

# Check against multiple frameworks
kestrel scan --frameworks fips_140_3,pci_dss_4

Output Formats

# JSON output
kestrel scan --json --output results.json

# SARIF output (GitHub Advanced Security)
kestrel scan --sarif --output results.sarif

# HTML report
kestrel scan --html --output report.html

# CycloneDX CBOM report
kestrel scan --cbom --output cbom.json

Notes:

• JSON output deduplicates findings by algorithm and source location.
• CBOM output uses CycloneDX 1.6 and SARIF output uses SARIF 2.1.0.

CBOM Auditing

# Audit a CycloneDX CBOM against compliance frameworks
kestrel cbom-audit --input cbom.json --frameworks fips_140_3,pci_dss_4

# Disable schema validation (defaults to true)
kestrel cbom-audit --input cbom.json --schema-validate=false

Schema validation uses the CycloneDX JSON schema via sbom-validator.

Semgrep Controls

# Disable Semgrep scanning
kestrel scan --no-semgrep

# Run only Semgrep scanning
kestrel scan --semgrep-only

# Use a specific Semgrep config or pinned registry pack
kestrel scan --semgrep-config rules/semgrep/crypto.yml
kestrel scan --semgrep-config p/crypto@<version>

By default, Kestrel uses its curated Semgrep ruleset in rules/semgrep/crypto.yml. If that file isn't available (for example, when running only the installed binary), it falls back to p/crypto.

Example Output

Kestrel Report - 2025-08-20T03:28:37Z
=================================

SUMMARY
-------
Files Scanned:          1
Total Findings:         10
Total Violations:       8
Critical:               4
High:                   4
Medium:                 0
Low:                    0
Duration:               293.187µs

FIPS_140_3 VIOLATIONS
----------------------
Algorithm       Severity        Status          File                            Line    Message
---------       --------        ------          ----                            ----    -------
DES             CRITICAL        FORBIDDEN       examples/crypto_example.go      7       Algorithm DES is forbidden and must not be used
RC4             CRITICAL        FORBIDDEN       examples/crypto_example.go      8       Algorithm RC4 is forbidden and must not be used
MD5             HIGH            FORBIDDEN       examples/crypto_example.go      4       Algorithm MD5 is forbidden and must not be used
SHA1            HIGH            DEPRECATED      examples/crypto_example.go      5       Algorithm SHA1 is deprecated and should not be used

RECOMMENDATIONS
---------------
• Replace MD5 hash function with SHA-256 or SHA-3
• Migrate from SHA-1 to SHA-256 or higher for digital signatures
• Replace DES/3DES encryption with AES-128 or higher
• Replace RC4 stream cipher with AES in appropriate mode
• Address critical and high severity violations immediately

Supported Frameworks

FIPS 140-3

• Status: Implemented
• Algorithms: MD5, SHA-1, SHA-2, SHA-3, DES, 3DES, AES, RSA, ECDSA, and more
• Categories: Forbidden, Deprecated, Allowed

PCI DSS 4.0

• Status: Implemented
• Focus: Payment card data protection
• Stricter requirements: More algorithms marked as forbidden

Future Frameworks

• NIST SP 800-131A
• Common Criteria
• Custom framework definitions

Supported Languages

Current Support

• Go: Full AST-based scanning
  • Function call analysis
  • Key-size extraction (AES/RSA) and cipher mode signals
  • Type usage detection

Semgrep Coverage

• Python, JavaScript/TypeScript, Java, C/C++, and more

Configuration

Framework Rules

Rules are defined in YAML files in the rules/ directory:

name: "fips_140_3"
version: "2019"
description: "FIPS 140-3 compliance rules"

algorithms:
  - name: "MD5"
    type: "hash"
    status: "forbidden"
    severity: "high"
    remediation: "Replace with SHA-256 or SHA-3"

Scanner Configuration

// Go AST Scanner
goConfig := &scanner.GoASTConfig{
    IncludeTests:  false,
    ExcludeVendor: true,
}

CI/CD Integration

GitHub Actions

name: Kestrel Crypto Compliance
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-go@v3
      with:
        go-version: '1.21'

    - name: Install Kestrel
      run: go install github.com/harekrishnarai/kestrel/cmd/kestrel@latest

    - name: Run Kestrel
      run: kestrel scan --path . --sarif --output results.sarif

    - name: Upload SARIF
      uses: github/codeql-action/upload-sarif@v2
      with:
    sarif_file: results.sarif

Documentation Site (Docusaurus)

Kestrel docs are powered by Docusaurus and can be served locally.

npm install
npm run start

Build the static site:

npm run build

Documentation

• pkg.go.dev: https://pkg.go.dev/github.com/harekrishnarai/kestrel

License

Kestrel is licensed under the Apache License 2.0. See LICENSE for details.

Documentation

Overview

Package kestrel provides a CLI for cryptographic algorithm compliance auditing.