Skip to content

Repository files navigation

Bellerophon

OpenSSF Scorecard OpenSSF Best Practices: Passing CI License: Apache 2.0 SBOM Conventional Commits REUSE

Multi-protocol compliance validation with dual-agent cross-review.


The Problem

AI coding tools generate infrastructure faster than anyone can validate it. The result: DNS misconfigurations, expired certificates, weak cipher suites, and CA/Browser Forum violations that slip into production undetected.

Existing tools are reactive (scan after deploy), single-authority (one engine, one opinion), and passive (run once, forget). None of them separate the security verdict from the compliance verdict — so when they disagree, you never know.


The Solution

Bellerophon probes targets across protocol layers, evaluates the collected evidence against declarative OPA Rego policies, and detects what changed between checks. Two independent agents — one for security, one for compliance — run against the same evidence and cross-review each other's findings to produce a confidence-scored verdict.

Agreement means confidence. Disagreement means a finding.


The Mythological Reveal

In Greek mythology, Bellerophon rode the winged horse Pegasus to slay the Chimera — a fire-breathing hybrid that no single hero could face alone.

The names are not decoration. They map directly to the architecture:

  • Bellerophon (security agent) — asks: "Can this be exploited?" Evaluates security/ and shared/ policies. Thinks like an adversary.
  • Pegasus (compliance agent) — asks: "Does this meet the standard?" Evaluates compliance/ and shared/ policies. Validates against CA/Browser Forum Baseline Requirements and industry standards.
  • Chimera — the AI-generated code security platform that Bellerophon was built to validate. First consumer of these compliance reports.

When Bellerophon and Pegasus agree, you have a high-confidence verdict. When they disagree, the cross-review flags the divergence as a finding. Neither agent can self-approve.


Quick Start

# Clone and install
git clone https://github.com/Guipetris/bellerophon && cd bellerophon
cargo install --path .

# First check (text output, all policies)
bellerophon check https://your-target.com

# JSON output for scripting
bellerophon check https://your-target.com -f json

# Dual-agent cross-review (highest confidence)
bellerophon review https://your-target.com

Default --policy-dir is ./policies. Default --store-dir is ./evidence-store.


What It Probes

Layer What's Extracted Status
DNS IP resolution, endpoint discovery Active
TLS Certificate chain, key types/sizes, protocol version, cipher suite Active
HTTP Security headers (HSTS, CSP, X-Frame-Options), info leakage Coming Soon
OIDC Discovery document, signing algorithms, grant types Coming Soon
DNS CAA Certificate Authority Authorization records Coming Soon

What It Checks

Active Policies

Policy Agent What It Checks
shared/tls/certificate_chain_valid Both Chain has leaf + CA, links correctly, terminates at CA
shared/tls/certificate_not_expired Both No certificate in chain is expired or approaching expiry
shared/tls/minimum_key_strength Both RSA >= 2048 bits, ECDSA >= 256 bits
security/tls/weak_cipher_detection Bellerophon Protocol >= TLS 1.2, strong cipher suite, adequate key exchange
compliance/tls/cabf_baseline Pegasus CA/Browser Forum Baseline Requirements (validity period, key size, signature algorithm)

Stub Policies (Skip Until Probe Is Implemented)

Policy Awaiting
dns/caa_records_present DNS CAA probe
http/info_leakage HTTP probe
http/security_headers_present HTTP probe
oidc/discovery_present OIDC probe
oidc/secure_token_config OIDC probe

Stub policies are loaded but produce SKIP results when their required evidence type has not been collected. They do not fail the scan.


Output Formats

Format Flag Status Notes
Text -f text Implemented Colored terminal output with PASS/FAIL/WARN/SKIP/ERROR badges. Default.
JSON -f json Implemented Machine-readable. Includes full ComplianceReport + ChangeReport.
SARIF Planned GitHub Security tab integration.
HTML Planned Customer-facing branded report. Generator exists; not yet wired to CLI.

Scan Modes

Command What Runs Use When
bellerophon scan <TARGET> Bellerophon agent (security/ + shared/) You want a security-focused assessment
bellerophon audit <TARGET> Pegasus agent (compliance/ + shared/) You want a compliance-focused assessment
bellerophon review <TARGET> Both agents independently, then cross-review with confidence score You want the highest-confidence verdict
bellerophon check <TARGET> All policies (security/ + compliance/ + shared/ + stubs) Backward-compatible full scan

Each subcommand accepts the same flags: -p/--policy-dir, -s/--store-dir, -f/--format.


Change Detection

Run it twice and Bellerophon tells you what changed.

On the second run against the same target, with the same --store-dir, the tool compares the new results against the stored report from the previous check:

Changes since last check (2026-03-21T14:30:00Z)
  [REGRESSION  ] shared/tls/certificate_not_expired: pass -> fail — certificate expires in 3 days
  [IMPROVED    ] security/tls/weak_cipher_detection: fail -> pass — protocol upgraded to TLS 1.3
  [NEW         ] shared/tls/minimum_key_strength: pass — first evaluation

  Regressions: 1 | Improvements: 1

Change types: REGRESSION (pass to fail), IMPROVED (fail to pass), NEW (first evaluation), CHANGED (status shift), UNCHANGED.

Change detection requires a consistent --store-dir between runs. The default is ./evidence-store relative to the working directory.


Exit Codes

Code Meaning Use In CI
0 Compliant All evaluated policies passed
1 Non-compliant One or more policies failed
2 Degraded Warnings only, no hard failures
3 Error Probe failed, invalid target, or policy load error

Exit code 3 is used for infrastructure errors. Exit code 1 is the gating signal for deployment pipelines.

bellerophon check https://target.com || exit 1

Product Vision

Bellerophon is being built toward three capabilities:

Discovery (current) — Probe live targets, evaluate against policies, detect drift between checks. Give engineers a compliance posture snapshot they can run in CI.

Certification (next) — Package compliance reports as W3C Verifiable Credentials (SD-JWT-VC format). A signed, cryptographically verifiable attestation that a target passed a specific set of policies at a specific point in time.

Alerting (planned) — Watch mode with continuous monitoring. Detect regressions the moment they appear — certificate near-expiry, cipher suite downgrade, chain validity failure — and emit structured alerts before they reach production.


Roadmap

Planned features, in approximate order:

  • HTTP security headers probe (HSTS, CSP, X-Frame-Options, info leakage detection)
  • OIDC discovery probe (signing algorithms, grant types, discovery document validation)
  • DNS CAA probe (Certificate Authority Authorization record validation)
  • SARIF v2.1.0 output (GitHub Security tab integration)
  • HTML report output (customer-facing branded report; generator exists, CLI wiring pending)
  • Watch mode (bellerophon watch) for continuous monitoring
  • S3 evidence store backend (object lock, DynamoDB index, KMS encryption)
  • W3C Verifiable Credentials output for compliance certification

Standards Mapping

Bellerophon probes and policies are mapped to industry threat frameworks and standards:

Framework Coverage Reference
MITRE ATLAS (AI/ML threats) 13 AI probes mapped to ATLAS techniques docs/mitre-atlas-mapping.md
MITRE ATT&CK (infrastructure) 9 infrastructure probes mapped to ATT&CK docs/mitre-atlas-mapping.md
OWASP Top 10 for LLMs Certification profile with 10 controls Certification profile: owasp-llm-top10
OWASP ASVS v4 11 controls (HTTP, TLS, CORS) Certification profile: owasp-asvs
EU AI Act Article-level control mapping Certification profile: eu-ai-act
ISO/IEC 42001 AI management system controls Certification profile: iso-42001
NIST AI RMF Govern/Map/Measure/Manage functions Certification profile: nist-ai-rmf

OWASP project application: docs/owasp-project-application.md


Relationship to Chimera

Chimera is a trust-as-a-service platform for AI-generated code security. It uses weighted voting across multiple validation agents to assign a trust score to generated artifacts. Bellerophon is the forward-edge discovery and validation layer: it probes the infrastructure that Chimera and its consumers depend on, and its compliance reports feed into Chimera's trust signal pipeline. Bellerophon validates Chimera; Chimera consumes the reports. The relationship is not circular — Bellerophon has no dependency on Chimera at runtime. See docs/chimera-integration.md for the planned integration architecture.


License

Apache License 2.0

About

Compliance Gate Engine — multi-protocol compliance validation system

Topics

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages