HefestoAI checks AI-generated code before you ship it.
HefestoAI Model Context Protocol (MCP) Server
The io.github.artvepa80/hefestoai MCP server is a pre-commit code quality guardian that detects semantic drift in AI-generated code. It checks whether a project’s declared items—such as dependencies, configurations, and install artifacts—match what the project actually does before changes ship.
🛠️ Key Features
Detects semantic drift in AI-generated code
Verifies declared deps, configs, and install artifacts against real outcomes
Provides 4 tools (toolCount: 4)
🚀 Use Cases
Pre-commit validation for repositories using AI-generated code
Ensuring declared project state matches installation and behavior
Catching mismatches before release
⚡ Developer Benefits
Adds a release- and shipping-time verification step for AI-authored changes
Helps prevent inconsistencies between project declarations and actual install artifacts
⚠️ Limitations
Scope described is centered on semantic drift and verification of declared vs. actual deps/configs/install artifacts
Runs the open-source hefesto-ai engine (`hefesto analyze --no-config`, free tier) on the files you send to the hosted analyzer and returns its findings: rule id, severity, file, line, message and the SARIF hefestoFingerprint/v1 fingerprint (format "sarif" adds the full SARIF 2.1.0 log). Use it to check a file or snippet the user shares (for example "analyze this file") for security and quality issues before committing. Try it: {"code":"password = \"Sup3rS3cret!2026\""} returns a HARDCODED_SECRET finding. Minimum call: {"code": "<file contents>"}. Add path (e.g. "app/run.py") so the language comes from the extension; without path or language the language is inferred from the content, else python. For several files send files=[{"path", "content"}] instead. severity and format are optional. Covers Python, COBOL, the DevOps/IaC formats hefesto analyze routes, and TypeScript, JavaScript, Java, Go, Rust and C# through the multilang tree-sitter grammars (the first such request on a fresh server instance downloads the grammars and can take a few seconds longer). Limits: 20 files, 100 KB per file, 256 KB in total, 20 seconds, 10 requests per minute per IP, shared across server instances. No .hefesto.yaml is read. Files are deleted after the run; nothing is stored. For a whole repository, run `hefesto analyze .` locally.
Parameters6
files
array
optional
Several files to analyze. Used instead of code when present. path: relative POSIX, at most 200 characters and 8 levels; each segment is letters, digits, "_", "." or "-" and must not start with "-"; no "..", no absolute paths, no ".git" or ".hefesto.yaml". content: UTF-8 text, no NUL bytes, at most 100 KB.
code
string
optional
Contents of one file or snippet, used when files is omitted. At most 100 KB. This is the only argument a first call needs.
path
string
optional
Optional file name for code, e.g. "app/run.py" or "Dockerfile". The extension picks the language. Same rules as files[].path. Ignored when files is set.
language
string
optional
Optional language of code. Ignored when files or path is set. When omitted it is inferred from the content (python if unsure). An unknown language is rejected; send path or files instead.
severity
string
optional
Optional minimum severity to report (default LOW).
format
string
optional
Optional. json (default): findings only; sarif: also the full SARIF 2.1.0 log.
Raw schema
{
"type": "object",
"properties": {
"files": {
"type": "array",
"maxItems": 20,
"description": "Several files to analyze. Used instead of code when present. path: relative POSIX, at most 200 characters and 8 levels; each segment is letters, digits, \"_\", \".\" or \"-\" and must not start with \"-\"; no \"..\", no absolute paths, no \".git\" or \".hefesto.yaml\". content: UTF-8 text, no NUL bytes, at most 100 KB.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"path": {
"type": "string",
"maxLength": 200,
"description": "Relative POSIX path. The extension picks the language."
},
"content": {
"type": "string",
"description": "UTF-8 source text. At most 100 KB. No NUL bytes."
}
},
"required": [
"path",
"content"
]
}
},
"code": {
"type": "string",
"description": "Contents of one file or snippet, used when files is omitted. At most 100 KB. This is the only argument a first call needs."
},
"path": {
"type": "string",
"description": "Optional file name for code, e.g. \"app/run.py\" or \"Dockerfile\". The extension picks the language. Same rules as files[].path. Ignored when files is set."
},
"language": {
"type": "string",
"enum": [
"python",
"py",
"cobol",
"yaml",
"yml",
"dockerfile",
"docker",
"terraform",
"hcl",
"shell",
"bash",
"sh",
"sql",
"javascript",
"js",
"typescript",
"ts",
"java",
"go",
"rust",
"csharp",
"c#"
],
"description": "Optional language of code. Ignored when files or path is set. When omitted it is inferred from the content (python if unsure). An unknown language is rejected; send path or files instead."
},
"severity": {
"type": "string",
"enum": [
"LOW",
"MEDIUM",
"HIGH",
"CRITICAL"
],
"description": "Optional minimum severity to report (default LOW)."
},
"format": {
"type": "string",
"enum": [
"json",
"sarif"
],
"description": "Optional. json (default): findings only; sarif: also the full SARIF 2.1.0 log."
}
},
"additionalProperties": false,
"description": "Send code (one file; path and language optional) or files (several). Everything else is optional.",
"examples": [
{
"code": "import sqlite3\n\npassword = \"Sup3rS3cret!2026\"\n\n\ndef find_user(db, name):\n return db.execute(\"SELECT * FROM users WHERE name = '\" + name + \"'\")\n"
},
{
"code": "import sqlite3\n\npassword = \"Sup3rS3cret!2026\"\n\n\ndef find_user(db, name):\n return db.execute(\"SELECT * FROM users WHERE name = '\" + name + \"'\")\n",
"path": "app/users.py",
"severity": "MEDIUM"
},
{
"files": [
{
"path": "src/users.py",
"content": "import sqlite3\n\npassword = \"Sup3rS3cret!2026\"\n\n\ndef find_user(db, name):\n return db.execute(\"SELECT * FROM users WHERE name = '\" + name + \"'\")\n"
}
]
}
]
}
pricing
Return current HefestoAI prices (Free $0, PRO $8/month per user, OMEGA $19/month). Use it when the user asks what HefestoAI costs. Static text. Does not look up or change a subscription. No parameters: call it with {}.
Return install commands for the open-source package (pip install hefesto-ai, Python 3.10+). Use it when the user wants to run HefestoAI locally, in a pre-commit hook or on a whole repository. Does not install anything on the caller's machine. No parameters: call it with {}.
Return a short static comparison of HefestoAI with one named tool. Use it when the user asks how HefestoAI differs from another scanner. No live lookup and no code is inspected. All arguments are optional: {} compares with sonarqube. Known values: sonarqube (the default when tool is omitted), snyk, github-advanced-security, semgrep, claude-code-security, coderabbit, qodo. Any other value is answered as sonarqube.
Parameters1
tool
string
optional
Optional. Tool to compare with: sonarqube (default), snyk, github-advanced-security, semgrep, claude-code-security, coderabbit, or qodo.
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.
Deterministic pass/fail check for agent-written code. It compares what your repo declares (dependencies, README, pyproject.toml, CHANGELOG, action.yml, CI) with what it actually does, and flags secrets and risky IaC. Same input, same result.
Findings show up under Security > Code scanning and as pull request annotations. Public repositories work as shown; private repositories without GitHub Code Security set upload_sarif: 'false' (the SARIF file is still written). @v4 follows every 4.x release, minors included (4.16.0 made a run that analyzes no files fail the gate). For a fixed version, pin artvepa80/Agents-Hefesto@v4.22.0 or a commit SHA. The Action runs the same formats as hefesto analyze: Python plus YAML, Terraform, Shell, Dockerfile, SQL, PowerShell, JSON, TOML, Makefile, Groovy, COBOL, CloudFormation, ARM, Helm and Serverless, plus the drift checks. TypeScript, JavaScript, Java, Go, Rust and C# need multilang: 'true' in the Action (opt-in) or the CLI with pip install "hefesto-ai[multilang]".
Free and MIT. PRO ($8/mo per user) and OMEGA ($19/mo): plans.
Operational Truth Analyzers (v4.22.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 read by any scripts/action_*.sh; 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
bash
# All operational truth findings appear in standard output
hefesto analyze . --severity MEDIUM
Quick Start
bash
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 (known public client keys such as PostHog phc_ and Stripe pk_live_/pk_test_ are reported as LOW)
SQL_INJECTION_RISK
HIGH
String concatenation in queries
COMMAND_INJECTION
HIGH
Unsafe shell command execution
PICKLE_USAGE
HIGH
import pickle / cPickle lines (the import is flagged; pickle.loads() calls are not reported separately)
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
python
# 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)
@v4 is a floating tag that follows the whole 4.x line, minor releases included: every v4.x.y release moves it, so the workflow gets fixes without edits, and also behaviour changes such as the 4.16.0 change that makes a run with no analyzed files fail --fail-on (exit 1; --allow-no-files opts out). If you need exact stability, pin an exact release tag such as artvepa80/Agents-Hefesto@v4.22.0 (exact tags never move) or a commit SHA, and bump it yourself.
With SARIF upload to GitHub code scanning (findings appear under Security > Code scanning and as pull request annotations):
yaml
jobs:hefesto:runs-on:ubuntu-latestpermissions:contents:readsecurity-events:write# upload-sarifactions:read# private repositories onlysteps:-uses:actions/checkout@v4-uses:artvepa80/Agents-Hefesto@v4# SARIF needs v4.15.0 or laterwith: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.11 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
allow_no_files
true: passes --allow-no-files, so a run that analyzes no files keeps exit 0 under fail_on (intentionally empty target); the warning is still printed
false
allow_not_analyzed
true: passes --allow-not-analyzed, so a found file that could not be analyzed does not fail fail_on; the file is still listed as "Not analyzed" and warned about
false
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
multilang
Opt-in. true: installs the [multilang] extra, so TypeScript, JavaScript, Java, Go, Rust and C# files are analyzed too (grammars are downloaded on the first run; a file whose grammar cannot be loaded fails fail_on)
false
telemetry
Opt-in. Only 1 or true enables telemetry: the Action sends one anonymous ping per run (no id) and the CLI sends its pseudonymous usage events (random install id). Any other value, including the default 0, sends no telemetry (the CLI still checks pypi.org for a newer version); see docs/telemetry.md
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 a local MCP server:
bash
uvx hefesto-mcp
HEFESTO_MCP_ROOT is required (the project directory; not / or the home directory). See Local MCP (stdio).
Add to Cursor (one click):
The button opens Cursor's install prompt through cursor.com/link (GitHub does not render cursor:// links). Direct deeplink: cursor://anysphere.cursor-deeplink/mcp/install?name=hefestoai&config=eyJ1cmwiOiJodHRwczovL2hlZmVzdG9haS5uYXJhcGFsbGMuY29tL2FwaS9tY3AtcHJvdG9jb2wifQ%3D%3D. The same server is in .mcp.json at the repository root ({"mcpServers":{"hefestoai":{"url":"https://hefestoai.narapallc.com/api/mcp-protocol"}}}). No API key.
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; the hosted MCP runs a recent hefesto-ai release) 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.
The hosted MCP server is closed-source and operated by Narapa LLC. server.json keeps repository on this public repository because it contains the open-source hefesto-ai engine that analyze runs.
Local MCP (stdio)
The mcp extra runs the local engine over stdio. It does not call the hosted service. It is on PyPI since hefesto-ai 4.21.0: pip install "hefesto-ai[mcp]" or uvx hefesto-mcp. The extra requires mcp>=1.7,<2 and Python 3.11 or newer, the package requires-python (the mcp dependency requires Python >= 3.10, which every supported Python meets, so the extra has no separate environment marker). HEFESTO_MCP_ROOT is required: set it to the project directory the tools may read. That directory must not resolve to / or the home directory. A relative path is joined to that directory, not to the process working directory.
bash
pip install "hefesto-ai[mcp]"
An MCP client launches it with stdio. Pass the project directory in HEFESTO_MCP_ROOT (--root still overrides it). Paths outside that directory are rejected.
Tools: analyze_local (a file or directory inside that root) and version. Details: docs/local-mcp.md.
PR Review (v4.22.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).
bash
# 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
# Exit 1 if the diff adds a `# hefesto: ignore[TYPE] reason` comment
hefesto pr-review --fail-on-new-suppressions
On Python files, # hefesto: ignore[TYPE] reason on the line a finding is reported on suppresses that finding, up to HIGH; CRITICAL findings are never suppressed. The reason is required. Several types can be listed (ignore[A, B] reason). A directive with no reason, no [TYPE], or no matching finding suppresses nothing and prints a warning. Other languages are not read yet. hefesto pr-review includes new_suppressions (each suppression comment the diff adds, with its reason). --fail-on-new-suppressions exits 1 when the diff adds one.
How it works:
Parses git diff between base and head (auto-detects origin/main or GITHUB_BASE_REF)
Runs the full analyzer suite on touched files only
Filters findings to changed lines (default) or full files (--strict). A function-level finding (complexity, long function, deep nesting) is reported on the def line and counts as changed when any added line falls inside the function. Its line stays on the def line, so the dedup key does not move, and anchor_line is the added line that inline comments go on (null outside a hunk)
Emits JSON with SHA256 dedup keys for each finding
¹ 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).
³ C and C++ are experimental and off by default: turn them on with
--experimental c-cpp (or experimental: [c-cpp] in .hefesto.yaml). The generic complexity and size checks run on
them; with --experimental c-cpp,lang-security the C/C++ security rules
CC001-CC004 also run (docs/ANALYSIS_RULES.md). They are not counted in the
format total below. .h headers are read as C unless they contain C++-only
syntax or sit next to a C++ source with the same name; headers with
Objective-C syntax (@interface, @class, ...) are skipped. Details:
docs/c-cpp.md.
With --experimental lang-security and [multilang], these security rules also run: CS001–CS004 (C#), GO001, GO003 and GO004 (Go), and RS001–RS003 (Rust); with --experimental c-cpp,lang-security, also CC001–CC004 (C and C++). See docs/ANALYSIS_RULES.md.
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
Yes
JSON
J001, J002, J004, J005
4 security rules
v4.5.0
Yes
TOML
T001-T003
3 security rules
v4.5.0
Yes
Makefile
MF001-MF005
5 security rules
v4.5.0
Yes
Groovy
GJ001-GJ005
5 security rules
v4.5.0
Yes
COBOL
CobolGovernanceAnalyzer
COBOL001-COBOL016 (16 free rules)²
v4.12.0
Yes
Cloud Infrastructure
Format
Analyzer
Focus
Status
Run by hefesto analyze
CloudFormation
CloudFormationAnalyzer
AWS IaC Security
v4.7.0
Yes
ARM Templates
ArmAnalyzer
Azure IaC Security
v4.7.0
Yes
Helm Charts
HelmAnalyzer
Kubernetes Security
v4.7.0
Yes
Serverless
ServerlessAnalyzer
Serverless Framework
v4.7.0
Yes
Total: the package ships analyzers for 22 formats (7 code languages + 11 DevOps formats + 4 Cloud formats). hefesto analyze (which the GitHub Action and the pre-push hook call) runs all 22, plus C and C++ with --experimental c-cpp and [multilang]. When a suffix matches more than one format, the precedence table in docs/design/devops-analyzers-wiring.md chooses one analyzer.
² COBOL: all 16 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/COBOL016, COBOL007 and COBOL015 for their own nested COPYs; the other rules are not applied to them).
# 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]"# Optional: local stdio MCP adapter (on PyPI since hefesto-ai 4.21.0)
pip install "hefesto-ai[mcp]"# or: uvx hefesto-mcp# HEFESTO_MCP_ROOT is required (project directory; not / or home).
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.
HefestoAI 4.22.0 requires Python 3.11 or newer. On Python 3.10, the command above succeeds but stays on 4.20.4; upgrade Python first, or pin hefesto-ai==4.20.4.
Changes since 4.17 that can affect existing setups (details in CHANGELOG.md):
More files are analyzed. PowerShell, JSON, TOML, Makefile, Groovy, CloudFormation, ARM, Helm and Serverless files are checked (4.20.0), so a --fail-on gate that passed before can fail.
Files that were found but not analyzed fail --fail-on (4.20.1, 4.21.0). Pass --allow-not-analyzed (Action: allow_not_analyzed: 'true') to keep the old exit code; such files are still listed.
Telemetry. Anonymous usage events go to PostHog and are on by default (4.18.0). hefesto telemetry status and clear were removed. Opt out with hefesto telemetry disable, HEFESTO_TELEMETRY=0 or DO_NOT_TRACK=1.
Messages. For tree-sitter languages (C#, Go, Rust, TypeScript and others), some finding messages and the JSON function field now name the declared method or type (4.21.0). Line numbers, rule types and counts are unchanged, but hefesto pr-review may post comments again on pull requests it already reviewed.
GitHub Action pinned to @v4.17.x:
To keep an exact pin, change it to artvepa80/Agents-Hefesto@v4.22.0 (or that release's commit SHA). To follow every 4.x release, including minor releases that change behaviour, use @v4.
Either way, the runner needs python3 3.11 or newer. ubuntu-latest has it. On ubuntu-22.04, add actions/setup-python with python-version: '3.11' before the Action.
Older than 4.17? Also read the CHANGELOG entries for the releases in between (for example, since 4.16.0 a run that analyzes no files fails --fail-on; --allow-no-files opts out).
CLI Reference (v4.22.0)
bash
# 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
hefesto analyze . --include-vendored # also analyze vendored/minified JS (skipped by default)# Analyze COBOL with program lineage in the JSON report (JSON only)
hefesto analyze . --output json --lineage
# 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
hefesto pr-review --fail-on-new-suppressions # exit 1 if the diff adds a suppression# Check the installation and dependencies
hefesto check
# License (PRO/OMEGA): print the export or unset line; nothing is stored
hefesto activate HFST-XXXX-XXXX-XXXX-XXXX-XXXX
hefesto deactivate
# Check status
hefesto status
# Install/update git hook
hefesto install-hooks
# Start API server (PRO)
hefesto serve --port 8000
# Telemetry (on by default)
hefesto telemetry disable
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;
CWE, from one mapping (CWE list 4.20): GitHub code scanning reads the rule tag external/cwe/cwe-N (no zero-padding). The same id is a run.taxonomies CWE entry (organization MITRE) with a relationships kind on the rule (equal, superset or relevant). Python: secrets 798, SQL injection 89, command injection 78, eval/exec 95, bare except 396, pickle import 502 (relevant, precision low, because only the import is flagged). Assert has no CWE. A finding's metadata.cwe overrides the table; existing COBOL tags (cwe-798, cwe-20) stay as written. Table: docs/ANALYSIS_RULES.md;
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:
bash
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 no file was analyzed under --fail-on) or runtime error
2
Invalid command-line usage or invalid .hefesto.yaml
Gate Examples
bash
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)
hefesto analyze . --fail-on high --allow-no-files # an empty run keeps exit 0
hefesto analyze . --fail-on high --allow-not-analyzed # a file that failed does not fail the gate
A run that analyzes no files (empty directory, only unsupported files, or every
file excluded) is never reported as a pass: the report says "No files were
analyzed", a warning naming the path goes to stderr, and with --fail-on the
gate fails with exit 1. When files were left out as vendored JavaScript, the
warning names how many and suggests --include-vendored.
For runs that are empty on purpose (a changed-files-only job on a PR that
touches only Markdown, a monorepo matrix entry with no supported sources), pass
--allow-no-files (the Action's allow_no_files: 'true' input passes it for
you). Only the exit code changes: the run keeps exit 0 and prints "Gate
skipped: no files were analyzed (--allow-no-files)", while "Files analyzed: 0",
"No files were analyzed" and the stderr warning are still printed. It is a
command-line flag only: .hefesto.yaml cannot set it (an allow_no_files key
is rejected as unknown, exit 2), so a shared config never turns this check off.
A file that is not valid UTF-8 is read with the latin-1 fallback and
analyzed (its findings count); the text report lists it under "Decoded with
fallback (latin-1)", --output json has it in meta.decoded_with_fallback,
SARIF has a warning notification for it, and stderr warns about it.
A file the run found but could not analyze (it could not be read, its
analyzer raised an error, or its tree-sitter grammar could not be loaded, for
example offline, or with an empty or damaged grammar cache) is never dropped silently: the text report lists it
under "Not analyzed" with the reason, --output json has it in
meta.not_analyzed (path, language, reason: read_error,
analyzer_error, grammar_unavailable or parse_error (an experimental C/C++
file where the grammar recovered no declaration), exception; a grammar_unavailable
entry also names the grammar), SARIF has an error notification for it in
invocations[0].toolExecutionNotifications, and a warning goes to stderr (also
with --quiet). With --fail-on such a file fails the gate with "Gate failure:
N file(s) could not be analyzed (exit 1)", also when --allow-no-files is set.
--allow-not-analyzed (the Action's allow_not_analyzed: 'true' input) opts
out: the gate then judges only the findings, and the file is still listed and
warned about. Like --allow-no-files, it is a command-line flag only.
--allow-not-analyzed does not cover a path where no file was analyzed at
all (for example hefesto analyze a.ts without the TypeScript parser): that is
the zero-files case, which still exits 1 with --fail-on unless
--allow-no-files is set. When a missing parser is the cause, the warning says
so: parser unavailable for typescript (pip install "hefesto-ai[multilang]").
A file whose grammar could not be loaded counts as not analyzed even when
every file hit it, so --fail-on with --allow-no-files (as in the hooks from
hefesto install-hooks) exits 1 offline with an empty grammar cache. The cache
is per pack version. To fix it, run once with network access, or
python -c "import tree_sitter_language_pack as p; p.download(['java','go','rust','csharp','c','cpp','javascript','typescript'])",
or pass --allow-not-analyzed. A grammar that fails to load is tried once
per run: later files of that language are reported as not analyzed without
waiting for the download again.
Pre-Push Hook
In your own project, hefesto install-hooks installs the hooks shipped with the package: pre-commit analyzes the staged (index) content of the staged files (--fail-on HIGH), pre-push analyzes the repository (--fail-on CRITICAL). The hooks call the Python interpreter that ran install-hooks (python -m hefesto), fall back to hefesto on PATH, and fail with a message if neither is found (reinstall the hooks or set SKIP_HEFESTO_HOOKS=1). The hooks go to git rev-parse --git-path hooks, so worktrees and submodules work; if core.hooksPath is set (Husky, lefthook...), nothing is written and the command exits 1: call python -m hefesto analyze from that hook manager or use the hefesto-analyze pre-commit framework hook (see pre-commit Hook). It also exits 1 when no hook was installed (for example, existing hooks without --force). The contributor hooks from scripts/git-hooks/ described below are used only in a clone of Agents-Hefesto (root pyproject.toml with name = "hefesto-ai"); the command says which set it installed.
Automatic validation before every git push in this repository:
bash
# Install the same hooks and print the plans link (PRO $8/mo, OMEGA $19/mo)
hefesto init
# Install/update hooks
hefesto install-hooks
# Update an existing hook
hefesto install-hooks --force
# Bypass temporarily
SKIP_HEFESTO_HOOKS=1 git push
Fast lint/test gate — Black, isort, Flake8, and a minimal test suite
Note: Hooks are local to your machine and not committed to git. Run hefesto install-hooks after cloning, or hefesto install-hooks --force to replace existing hooks.
Hefesto OSS works standalone. If Hefesto PRO is installed, OSS can optionally enable:
Patch C API hardening for hefesto serve, scope gating (first-party by default), TS/JS
symbol discovery, and safe deterministic enrichment (schema-first, masked, bounded).
See docs/PRO_OPTIONAL_FEATURES.md.
REST API (PRO), OMEGA Guardian and IRIS
hefesto serve (PRO) exposes the analyzer over HTTP: docs/rest-api.md. OMEGA Guardian and the IRIS production-monitoring agent: docs/omega-iris.md.
hefesto analyze takes its options from command-line flags (see CLI
Reference above) and, optionally, from a .hefesto.yaml file (below). There
is no environment variable for analysis options such as severity or output
format.
Environment Variables
bash
# Telemetry (see Telemetry below)export HEFESTO_TELEMETRY=0 # Disable usage events# PRO/OMEGA only (read by the private distribution, ignored by the FREE tier)export HEFESTO_LICENSE_KEY="your-key"# API Security (PRO, v4.7.0) -- used by `hefesto serve`export HEFESTO_API_KEY="your-api-key"# Enable API key authexport HEFESTO_RATE_LIMIT_PER_MINUTE=60 # Enable rate limitingexport HEFESTO_CORS_ORIGINS="https://app.example.com"# Restrict CORSexport HEFESTO_EXPOSE_DOCS=1 # Enable /docs, /redocexport HEFESTO_WORKSPACE_ROOT="/srv/code"# Path sandbox rootexport HEFESTO_CACHE_MAX_SIZE=1000 # Cache size limitexport HEFESTO_CACHE_TTL_SECONDS=300 # Cache entry TTL
Config File (.hefesto.yaml)
Put the hefesto analyze options you would otherwise repeat on every run in a
.hefesto.yaml (or .hefesto.yml) file, usually at the repository root:
yaml
# .hefesto.yaml -- every key is optional and maps to a `hefesto analyze` flagseverity:MEDIUM# --severity LOW | MEDIUM | HIGH | CRITICALfail_on:HIGH# --fail-on LOW | MEDIUM | HIGH | CRITICALoutput:text# --output text | json | html | sarifexclude:# --exclude list or "a/,b/" string-tests/-node_modules/exclude_types:# --exclude-types list or comma-separated string-VERY_HIGH_COMPLEXITY-LONG_FUNCTIONquiet:false# --quietmax_issues:50# --max-issuesformat_check:true# --format-check (needs: pip install "hefesto-ai[format]")enable_memory_budget_gate:false# --enable-memory-budget-gatecopybook_paths:# --copybook-path (COBOL copybook directories outside the scan)-../copylib# relative paths are resolved from this file's directoryinclude_vendored:false# --include-vendored (analyze vendored/minified JavaScript too)experimental:# --experimental (comma-separated; the CLI value replaces this list)-c-cpp# C and C++ files (docs/c-cpp.md)-lang-security# C#, Go, Rust, C and C++ security rules (docs/ANALYSIS_RULES.md)
Excluded by default:.venv/, venv/, .tox/, node_modules/,
.git/, __pycache__/, dist/, build/, .mypy_cache/,
.pytest_cache/, .eggs/, *.egg-info/ (whole path components below the
analyzed path), plus vendored and minified JavaScript (.js, .mjs,
.cjs): *.min.js / *-min.js files, files under vendor/, vendors/,
bower_components/ or jspm_packages/, and files under a lib/, libs/,
plugins/, third_party/ or thirdparty/ directory inside static/,
assets/, public/ or wwwroot/ (for example static/js/libs/jquery.js).
A top-level lib/ is the project's own code and stays in scope, as do
non-JavaScript files under vendor/ (Go, PHP). --include-vendored (or
include_vendored: true) analyzes the JavaScript ones again; a single file
given on the command line is always analyzed.
The summary says how many were left out (N files skipped as vendored (use --include-vendored); meta.vendored_skipped in JSON, a tool notification in
SARIF).
critical_tests (preview): an optional section that maps requirements
to pytest tests for the critical-test regression guard. hefesto analyze
validates it and otherwise ignores it; see
docs/critical-tests.md.
exclude entries are path segments, not globs. Each entry matches
whole path components below the analyzed path (tests/fixtures/ skips
tests/fixtures/...); * and ** are taken literally, so
tests/fixtures/** or *.json match nothing even though "Excluding: ..."
lists them. A file or directory given explicitly on the command line is
not filtered by exclude.
Discovery: Hefesto starts at the first path given to hefesto analyze
(its directory if it is a file) and walks up to the repository root (the
first directory containing .git), or to the filesystem root outside a
repo. The nearest file wins. Both .hefesto.yaml and .hefesto.yml in one
directory is an error. With several paths, the first path's config applies
to the whole run (Hefesto warns if another path would pick a different file).
Precedence: explicit flag > config file > built-in default. A flag
counts as explicit even when it repeats the default (--severity MEDIUM
overrides severity: LOW). Lists are replaced, not merged:
--exclude docs/ ignores the file's exclude.
Flags:--config PATH uses that file instead of searching;
--no-config ignores config files. They cannot be combined.
Validation: unknown keys, bad values and invalid YAML stop the run with
exit code 2 and a message naming the problem, e.g.
Error: invalid Hefesto config in /repo/.hefesto.yaml: 'severity' must be one of LOW, MEDIUM, HIGH, CRITICAL (got 'urgent').
Keys may use - or _ (fail-on or fail_on); null means "not set".
The file in use is printed as Config: <path> (to stderr with
--output json; hidden with --quiet).
Only hefesto analyze reads it (not pr-review or the GitHub Action
inputs). Rule thresholds (cyclomatic complexity, etc.), --save-html and
the PRO scope/enrichment flags are not configurable through the file.
Credit-based, $0.012/credit; no permanent free plan
Free / Team $25/mo**
*Semgrep Supply Chain and Secrets are priced separately. **Snyk Team covers up to 10 developers; Enterprise is credit-based. Prices from each vendor's official pricing page, checked Oct 2026; they change often.
Where HefestoAI fits: most tools check code against the rules of its language. HefestoAI also checks a project against its own declarations: whether the imports match the declared dependencies, whether the versions in pyproject.toml, the CHANGELOG and the README agree, and whether action.yml and the Dockerfile match the files they reference.
Dogfooding (Honest Account)
We run HefestoAI's strict gate against HefestoAI's own code on every push to main. The gate has been GREEN since 2026-04-29, and getting there took more than six weeks: we logged the findings on 2026-03-17.
In strict mode, the gate flagged 12 complexity findings in our own gate-internals code (2 CRITICAL, 10 HIGH). We considered three responses: silence the findings (rejected — that's exactly the drift we critique), accept the override permanently (rejected — same reason), or refactor at root cause (chosen). The root-cause refactor itself was short once we started it: one PR, written over two days (2026-04-27 and 04-28) and merged on 2026-04-29. Along the way we also found a declared-vs-real drift in our own positioning doc and logged it for a fix.
The full audit and refactor history are tracked internally in our private repo. The refactor took the two CRITICAL functions from cyclomatic complexity 33 → 1 and 25 → 6, all helpers under 10. The 10 HIGH findings are under a temporary override whose mechanics and reversion criteria are documented.
Telemetry
The CLI sends pseudonymous usage events to PostHog by default (a random id; analyze also sends file and issue counts, duration, exit code, version, OS, Python, and ci/docker/dogfood plus pypi or editable — no code, file paths, findings or repository names, and no IP field in the payload). Turn them off with hefesto telemetry disable, HEFESTO_TELEMETRY=0, or DO_NOT_TRACK=1. The GitHub Action sends no usage events unless you set telemetry: 1. Separately, hefesto analyze asks pypi.org for the latest version (1.5 s timeout, cached for 24 hours). hefesto telemetry disable does not stop that check. From 4.20.3 the settings below skip it; 4.20.2 and earlier have no setting to disable it. Details: docs/telemetry.md.
The PyPI newer-version check is skipped, with no request and no cache write, when HEFESTO_NO_UPDATE_CHECK is 1, true, yes, or on, when HEFESTO_TELEMETRY is 0, false, no, or off, or when DO_NOT_TRACK is 1, true, yes, or on. Usage events stay on by default. The Action's default telemetry: 0 exports HEFESTO_TELEMETRY=0, so that check does not run on runners.
The code in this repository is licensed under the MIT License. The paid PRO and OMEGA features (the separately distributed hefesto_pro add-on) are covered by separate commercial terms in LICENSE-COMMERCIAL.md. Questions about licensing: sales@narapallc.com.
(c) 2026 Narapa LLC, Miami, Florida
Install
Tools (4)
analyzepricinginstallcompare
Remote endpoint
Streamable HTTP
Hosted server - connect over the network, no local install.