HefestoAI — release truth engine for AI-generated code

HefestoAI runs after your AI assistant writes the code and before it ships. It checks that what your project declares (dependencies, configs, install artifacts) matches what it actually does, and it runs security and complexity checks on the code itself.

---

Operational Truth Analyzers (v4.15.0)

These analyzers look for drift between what your project declares and what it does. They run on every hefesto analyze. The problems they look for don't live in any single file, so a per-file linter or security scanner won't report them: they show up only when you compare two files.

Analyzer	What it catches	Rule ID
Imports vs Deps	Python imports not declared in pyproject.toml or requirements.txt	OT-IMPORTS-001
Docs vs Entrypoints	CLI scripts in [project.scripts] missing from README	OT-DOCS-001
Packaging Parity	Version mismatch between pyproject.toml, CHANGELOG, and README badges	OT-PKG-001/002
Install Artifact Parity	action.yml inputs not consumed; Dockerfile COPY sources missing	OT-INSTALL-001/002
CI Config Drift	Python version or flake8 config mismatch between local and CI workflow	OT-CI-001/002/003

# All operational truth findings appear in standard output
hefesto analyze . --severity MEDIUM

---

Quick Start

pip install hefesto-ai
cd your-project
hefesto analyze . --fail-on critical

# PR review (added in v4.10.0) — analyze only changed code
hefesto pr-review
hefesto pr-review --strict        # include file-level context
hefesto pr-review --post --pr 42  # post inline comments via gh CLI

---

Why Hefesto? The AI Code Problem

Assistants such as Claude Code, GitHub Copilot and Cursor write code faster than anyone can review it line by line. Some of what they write passes a linter and is still dangerous:

• os.system(user_input) → command injection
• f"SELECT * FROM {table}" → SQL injection
• code that runs but quietly changes behavior, such as a misspelled attribute or an exception that is caught and dropped (checked in Python)

Hefesto checks for these at pre-commit, at pre-push and in CI, so they surface before the code reaches production.

---

What Hefesto Catches

Issue	Severity	Description
HARDCODED_SECRET	CRITICAL	API keys, passwords in code
SQL_INJECTION_RISK	HIGH	String concatenation in queries
COMMAND_INJECTION	HIGH	Unsafe shell command execution
PATH_TRAVERSAL	HIGH	Unsafe file path handling
UNSAFE_DESERIALIZATION	HIGH	pickle, yaml.unsafe_load
UNDECLARED_DEPENDENCY	MEDIUM	Import used but not in pyproject.toml
PACKAGING_VERSION_DRIFT	MEDIUM	Version mismatch across pyproject/CHANGELOG/README
CI_CONFIG_DRIFT	MEDIUM-HIGH	Local env vs CI configuration mismatch
INSTALL_ARTIFACT_DRIFT	MEDIUM-HIGH	action.yml inputs or Dockerfile COPY out of sync
HIGH_COMPLEXITY	HIGH	Cyclomatic complexity > 10
DEEP_NESTING	HIGH	Nesting depth > 4 levels
GOD_CLASS	HIGH	Classes > 500 lines
LONG_FUNCTION	MEDIUM	Functions > 50 lines
LONG_PARAMETER_LIST	MEDIUM	Functions with > 5 parameters

# Hefesto catches:
password = "admin123"  # HARDCODED_SECRET
query = f"SELECT * FROM users WHERE id={id}"  # SQL_INJECTION_RISK
os.system(f"rm {user_input}")  # COMMAND_INJECTION

# Hefesto suggests:
password = os.getenv("PASSWORD")
cursor.execute("SELECT * FROM users WHERE id=?", (id,))
subprocess.run(["rm", user_input], check=True)

---

GitHub Action

steps:
  - uses: actions/checkout@v4
  - name: Run Hefesto Guardian
    uses: artvepa80/Agents-Hefesto@v4.15.0
    with:
      target: '.'
      fail_on: 'CRITICAL'

With SARIF upload to GitHub code scanning (findings appear under Security > Code scanning and as pull request annotations):

jobs:
  hefesto:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # upload-sarif
      actions: read            # private repositories only
    steps:
      - uses: actions/checkout@v4
      - uses: artvepa80/Agents-Hefesto@v4.15.0   # SARIF needs v4.15.0 or later
        with:
          target: '.'
          fail_on: 'CRITICAL'
          sarif: 'true'

The Action is a composite action: it installs HefestoAI from the Action's own checkout into a private virtualenv (needs python3 >= 3.10 on the runner; ubuntu-latest has it), runs hefesto analyze, and with sarif: 'true' uploads the SARIF file with github/codeql-action/upload-sarif@v4, also when the fail_on gate fails. Full reference: docs/github-action.md.

Inputs:

Input	Description	Default
target	Path to analyze (file or directory)	.
fail_on	Exit with error if issues found at or above this severity level	CRITICAL
min_severity	Minimum severity to report (CRITICAL, HIGH, MEDIUM, LOW)	LOW
format	Output format printed to the log (text, json, html, sarif)	text
sarif	true: also write a SARIF 2.1.0 file and upload it to code scanning (needs security-events: write)	false
sarif_file	Path of the SARIF file	hefesto.sarif
upload_sarif	With sarif: true, upload the file; false only writes it	true
sarif_category	Code scanning category of the upload	hefesto
telemetry	Opt-in. Only 1 or true enables telemetry: the Action sends one anonymous ping per run and the CLI's anonymous ping is turned on. Any other value, including the default 0, sends nothing; see Telemetry	0

Outputs:

Output	Description
exit_code	The exit code of the CLI (0 = threshold not breached, 1 = fail_on threshold breached or runtime error; see Exit Codes)
sarif_file	Path of the SARIF file, when sarif is true and the file was written

---

AI-Generated Code Guardrails (Pre-commit + MCP)

HefestoAI can run as a pre-commit check or be called by an AI agent over MCP, so risky changes are flagged before merge.

Add as an MCP server:

npx @smithery/cli@latest mcp add artvepa80/hefestoai

API Endpoints:

Endpoint	Protocol	Path
MCP	JSON-RPC 2.0	/api/mcp-protocol
Hosted analysis	HTTP POST	/api/analyze
REST	HTTP GET/POST	/api/mcp
OpenAPI	OpenAPI 3.0	/api/openapi.json
Q&A	Natural Language	/api/ask
Changelog	JSON	/api/changelog.json
FAQ	JSON	/api/faq.json

The MCP analyze tool (and POST /api/analyze) runs the open-source engine (hefesto analyze --no-config, hefesto-ai 4.15.0) on the files you send: at most 20 files, 100 KB each, 256 KB in total, 20 seconds. It returns findings with rule ids, severities, lines and SARIF fingerprints. TypeScript, JavaScript, Java, Go, Rust and C# are covered too (multilang grammars; the first such request on a fresh server instance is a few seconds slower). Nothing is stored. For a whole repository, run hefesto analyze . locally.

---

PR Review (v4.15.0)

Analyze only the code changed in a pull request and post inline comments on the changed lines. Each finding carries a deterministic dedup key, so a workflow can skip findings it has already posted (the deduped template below does this; the simple one does not).

# Generate review as JSON (default — no network, no token needed)
hefesto pr-review

# Post inline comments via gh CLI (convenience mode)
hefesto pr-review --post --pr 42 --repo owner/name

# Include file-level context findings (not just changed lines)
hefesto pr-review --strict

How it works:

1. Parses git diff between base and head (auto-detects origin/main or GITHUB_BASE_REF)
2. Runs the full analyzer suite on touched files only
3. Filters findings to changed lines (default) or full files (--strict)
4. Emits JSON with SHA256 dedup keys for each finding

GitHub Actions workflow templates are provided under examples/github-actions/:

Template	Use case	Idempotent?
hefesto-pr-review-simple.yml	Quick onboarding, small repos	No (reruns duplicate)
hefesto-pr-review-deduped.yml	Production CI, teams	Yes (jq dedup pipeline)

See examples/github-actions/README.md for setup instructions.

---

Language Support

Code Languages

Language	Parser	Status
Python	Native AST	Full support
TypeScript	TreeSitter	Supported¹
JavaScript	TreeSitter	Supported¹
Java	TreeSitter	Supported¹
Go	TreeSitter	Supported¹
Rust	TreeSitter	Supported¹
C#	TreeSitter	Supported¹

¹ TreeSitter languages require the [multilang] extra: pip install "hefesto-ai[multilang]". Without it, files in these languages are skipped at parse time and Hefesto emits a stderr warning pointing to the install command (also exposed via report.meta.parser_failures in JSON output).

DevOps & Configuration

Format	Analyzer	Rules	Status	Run by hefesto analyze²
YAML	YamlAnalyzer	Generic YAML security	v4.4.0	Yes
Terraform	TerraformAnalyzer	TfSec-aligned rules	v4.4.0	Yes
Shell	ShellAnalyzer	ShellCheck-aligned	v4.4.0	Yes
Dockerfile	DockerfileAnalyzer	Hadolint-aligned	v4.4.0	Yes
SQL	SqlAnalyzer	SQL Injection prevention	v4.4.0	Yes
PowerShell	PS001-PS006	6 security rules	v4.5.0	Not yet
JSON	J001-J005	5 security rules	v4.5.0	Not yet
TOML	T001-T003	3 security rules	v4.5.0	Not yet
Makefile	MF001-MF005	5 security rules	v4.5.0	Not yet
Groovy	GJ001-GJ005	5 security rules	v4.5.0	Not yet
COBOL	CobolGovernanceAnalyzer	COBOL001-COBOL015 (15 free rules)³	v4.12.0	Yes

Cloud Infrastructure

Format	Analyzer	Focus	Status	Run by hefesto analyze²
CloudFormation	CloudFormationAnalyzer	AWS IaC Security	v4.7.0	Not yet
ARM Templates	ArmAnalyzer	Azure IaC Security	v4.7.0	Not yet
Helm Charts	HelmAnalyzer	Kubernetes Security	v4.7.0	Not yet
Serverless	ServerlessAnalyzer	Serverless Framework	v4.7.0	Not yet

Total: the package ships analyzers for 22 formats (7 code languages + 11 DevOps formats + 4 Cloud formats). In v4.15.0, hefesto analyze (which the GitHub Action and the pre-push hook call) runs 13 of them.

² The PowerShell, JSON, TOML, Makefile, Groovy, CloudFormation, ARM, Helm and Serverless analyzers are included and tested as modules, but the analysis engine does not route files to them yet, so these files are skipped by the CLI.

³ COBOL: all 15 rules are free; no license is needed. The analyzer is regex-based (no full COBOL parser) and reads .cbl, .cob, .cobol, .cpy and .pco files (lower or upper case), plus .dcl, .copy, .cbk and extension-less files that a scanned program COPYs or EXEC SQL INCLUDEs and that hold COBOL data definitions (copybooks get only the data rules COBOL004/COBOL008/COBOL009, COBOL007 and COBOL015 for their own nested COPYs; the other rules are not applied to them).

• Source format: a >>SOURCE FORMAT IS FREE/FIXED directive (or $SET SOURCEFORMAT(...)) in the first 50 lines decides the format. Without one, free format is inferred when a division header (or, in a copybook, a level-01/77 entry) starts before column 8; otherwise fixed format (columns 7-72) is assumed. The inference is a heuristic, so declare the directive if in doubt; the files read as free format this way are listed under Notes in the text report and in meta.cobol_format_notices (JSON).
• COBOL004 (REDEFINES) flags a REDEFINES only when one side holds packed (COMP-3), binary, float, pointer or signed numeric data and the two layouts differ (for example PIC X(12) over PIC S9(10)V99). Plain PIC X/unsigned display overlays, CICS BMS symbolic maps (and program overlays of a BMS input map, such as CardDemo's 01 FILLER REDEFINES CTRTLIAI) and the byte view of an unsigned binary integer (PIC 9(4) BINARY redefined as PIC X bytes of exactly its storage size, as CardDemo does to decode a VSAM file status) are skipped; a signed binary or a size mismatch is still flagged. COBOL005 reports one finding per OCCURS ... DEPENDING ON entry and skips the CICS DEPENDING ON EIBCALEN commarea idiom.
• COBOL006 / COBOL011 / COBOL015 report repeated findings once (per PERFORM X THRU Y pair, per program, per missing copybook), with the occurrence count and lines in the finding metadata.
• COBOL007 (copybook blast radius) is reported once on the copybook file when 5 or more scanned programs COPY it, directly or through nested copybooks (MEDIUM; HIGH at 15+ programs or for a generic name such as COMMON, UTILS, SHARED). It needs the copybook to be in the scan. COBOL015 (LOW) flags a COPY whose copybook is not in the scanned tree (also a nested COPY inside a copybook); it stays silent when no COPY in the scan resolves (for example a single file). Vendor copybooks (CICS DFH*, IBM MQ CMQ*, DB2 SQLCA/SQLDA) are skipped by both. EXEC SQL INCLUDE members count like COPY. Copybooks kept outside the scanned tree resolve with --copybook-path DIR (repeatable) or copybook_paths: in .hefesto.yaml; files there are expanded into the programs that COPY them but not analyzed on their own. The search below each copybook path is recursive but bounded: 8 directory levels and 50,000 files (a warning is logged when it stops), hidden directories skipped, and it runs once per run.
• COPY expansion: programs are analyzed with each COPY (and EXEC SQL INCLUDE) replaced by the copybook text, the way the compiler sees it, so every rule sees copybook data definitions, SELECTs and procedure code in the context of the program. COPY ... REPLACING is applied: ==pseudo-text== (including an empty replacement), literals, words and identifiers (A OF B, T(1)), LEADING/TRAILING partial words, and the ==:TAG:== / ==(TAG)== idioms inside words; matching is by text word (case-insensitive words, exact literals, first pair wins, no rescan). A REPLACING also applies to copybooks nested under it. Guards: a copybook already open in the chain is not expanded again (recursion), nesting stops at 16 levels and a program stops expanding after 250,000 copybook lines; a COPY that is not expanded stays as written. A finding on copybook text is reported at the program's COPY line with the copybook file and line in metadata.expanded_from; COBOL004/008/009 on an unchanged line of a scanned copybook stay on the copybook file (not repeated per program), but are reported in the program when REPLACING changed that line or the copybook comes from copybook_paths. Not supported: the REPLACE statement, and OF library does not pick between copybooks of the same name (the one closest to the program wins). Copybook files themselves are analyzed as written.
• COBOL002 (credentials) skips fields whose name ends in a flag/status/length/label suffix (for example WS-PASSWORD-OK-FLAG, PWD-LEN).
• COBOL008-COBOL010 (secrets, CRITICAL): a VALUE literal on a credential-named field (same suffix exclusions as COBOL002; placeholders such as SPACES, XXXX, UNDEFINED and key names such as 'APP-Token-Password' are skipped), PASS=/PWD=/PASSWORD= with a value inside any string literal, and EXEC SQL CONNECT ... USING/IDENTIFIED BY with a literal password.
• COBOL011 (LOW) flags SELECTs without a FILE STATUS clause, one finding per program with the file names in the metadata (sort files declared with SD are skipped). COBOL012 (LOW) flags an OPENed file whose status field, its subordinates and its 88-levels are never referenced in the PROCEDURE DIVISION (skipped when the status field is not defined in the expanded program, for example in a copybook that was not found, or the PROCEDURE DIVISION has a COPY that could not be expanded).
• COBOL013 (MEDIUM) flags statements after an unconditional STOP RUN/GOBACK/EXIT PROGRAM in the same paragraph (EXIT PROGRAM. STOP RUN. and alternate ENTRY points are not flagged). COBOL014 (LOW) flags paragraphs and sections that are never referenced (PERFORM, GO TO, THRU ranges, SORT/ALTER) and cannot be reached by fall-through; the entry paragraph, DECLARATIVES, empty EXIT paragraphs and programs with a PROCEDURE DIVISION COPY that could not be expanded are skipped.
• Measured recall: 39 of 41 seeded issues (every rule at least twice) are found, including 7 that only fire after COPY expansion; the 2 misses are documented limits: a secret whose value contains a credential word (skipped to avoid placeholder false positives) and a literal that reaches a password field through another field (no data-flow analysis). Run python scripts/cobol_recall.py; precision on real corpora is in docs/cobol-corpus-baseline.md.
• Performance: about 8 s per million lines on a synthetic 1,000-program project (1.05M lines, nested COPY and COPY ... REPLACING), about 4.5 s for a single 500,000-line program, with peak memory around 60 MB for the project and 250 MB for the 500k-line file (measured on an 8-vCPU Linux VM with Python 3.13; the analysis is single-threaded). Findings stay grouped, so a 500,000-line file yields 4 findings. Reproduce with python scripts/cobol_perf_bench.py.
• Output is text, JSON, HTML or SARIF 2.1.0 (--format sarif). In SARIF, a finding on copybook text carries the copybook file and line as a related location. A ready-to-push example repository layout (COBOL app with planted issues and a SARIF workflow) is described in docs/github-action.md.

---

Installation

# FREE tier
pip install hefesto-ai

# Required for TypeScript, JavaScript, Java, Go, Rust, and C# analysis
pip install "hefesto-ai[multilang]"

# Optional: Black, for `hefesto analyze --format-check`
pip install "hefesto-ai[format]"

pip install hefesto-ai installs the FREE tier only. For PRO or OMEGA, Narapa sends you an activation code after purchase, and the activation instructions come with it.

---

CLI Reference (v4.15.0)

# Analyze code
hefesto analyze <path>
hefesto analyze . --severity HIGH
hefesto analyze . --output json
hefesto analyze . --format sarif > hefesto.sarif   # SARIF 2.1.0 (--format is an alias of --output)
hefesto analyze . --sarif-file hefesto.sarif       # text report + SARIF file
hefesto analyze . --format-check   # opt-in: also report Black formatting drift
hefesto analyze . --config ci/hefesto.yaml    # explicit config file (see Configuration)
hefesto analyze . --no-config                 # ignore .hefesto.yaml
hefesto analyze src/ --copybook-path ../copylib  # COBOL copybooks outside the scan

# PR review (added in v4.10.0)
hefesto pr-review                              # JSON to stdout
hefesto pr-review --base main --head HEAD      # explicit refs
hefesto pr-review --strict                     # file-level findings too
hefesto pr-review --post --pr 42 --repo o/r    # post via gh CLI

# Check status
hefesto status

# Install/update git hook
hefesto install-hooks

# Start API server (PRO)
hefesto serve --port 8000

# Telemetry Management
hefesto telemetry status
hefesto telemetry clear

JSON Output

hefesto analyze . --output json          # stdout = pure JSON, banners -> stderr
hefesto analyze . --output json 2>/dev/null | jq .  # pipe-safe

SARIF Output

hefesto analyze . --format sarif > hefesto.sarif   # stdout = pure SARIF, banners -> stderr
hefesto analyze . --sarif-file out/hefesto.sarif   # any --output, plus a SARIF file

SARIF 2.1.0 for every finding hefesto analyze reports (all analyzers it runs, COBOL included, plus Operational Truth and provider findings), validated against the OASIS schema in the tests:

• one rule per rule ID (COBOL004, DOCKER010, ...; the issue type such as HARDCODED_SECRET when an analyzer has no ID) with name, description, help, help URI and a default level;
• level: CRITICAL/HIGH -> error, MEDIUM -> warning, LOW -> note; security rules (secrets, injection, unsafe commands, ...) also get security-severity (9.5 / 8.0 / 5.5 / 3.0), so GitHub rates them Critical/High/Medium/Low, plus CWE tags when known;
• repo-relative URIs (%SRCROOT%, the git top level of the current directory) and partialFingerprints built from the rule, the file and the text of the flagged line, so alerts keep their identity when code above them moves;
• GitHub upload limits: at most 25,000 results (highest severity kept) and 10 MB gzipped; anything dropped is reported in the log's tool notifications.

Columns are not reported (start line only).

Formatting Drift (opt-in)

hefesto analyze does not check formatting by default. With --format-check it also runs Black in check mode (in-process, files are never modified) on the Python files it analyzed:

pip install "hefesto-ai[format]"                    # or: pip install black
hefesto analyze . --format-check                    # report drift
hefesto analyze . --format-check --fail-on LOW      # fail the gate on drift

• Each file Black would reformat is one FORMAT_DRIFT finding, severity LOW. Because the check is opt-in, these findings are shown even when --severity is above LOW. --fail-on and --exclude-types apply to them like any other finding, so --fail-on MEDIUM (or higher) does not trip on drift.
• Black settings come from your pyproject.toml [tool.black] table, found the same way the black CLI finds it (line-length, target-version, skip-string-normalization, preview, extend-exclude / force-exclude, ...). If required-version does not match the installed Black, Hefesto warns.
• JSON output carries a unified diff (first 60 lines) in code_snippet and lines_added / lines_removed in metadata.
• If Black is not installed, Hefesto prints a one-line warning and continues; the exit code is unaffected.
• Only Black is covered; isort and flake8 are not run.

Exit Codes

Code	Meaning
0	Analysis complete (no --fail-on, or threshold not breached)
1	Gate failure (--fail-on threshold breached) or runtime error
2	Invalid command-line usage or invalid .hefesto.yaml

Gate Examples

hefesto analyze . --fail-on high         # exit 1 if HIGH+ found
hefesto analyze . --fail-on critical     # exit 1 only if CRITICAL found
hefesto analyze .                        # always exit 0 (report only)

---

Pre-Push Hook

Automatic validation before every git push:

# Install/update hook (copies scripts/git-hooks/pre-push -> .git/hooks/pre-push)
hefesto install-hooks

# Update an existing hook
hefesto install-hooks --force

# Bypass temporarily
SKIP_HEFESTO_HOOKS=1 git push