artvepa80/Agents-Hefesto

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.
Quick start (GitHub Action)
**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.19.0 or a commit SHA. The Action analyzes Python, YAML, Terraform, Shell, Dockerfile, SQL and COBOL plus the drift checks; TypeScript, JavaScript, Java, Go, Rust and C# need the CLI with pip install "hefesto-ai[multilang]".
Free and MIT. PRO ($8/mo) and OMEGA ($19/mo): plans.
---
Operational Truth Analyzers (v4.19.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 |
---
Quick Start
---
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 |
| PICKLE_USAGE | HIGH | pickle / cPickle imports (unsafe deserialization) |
| 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 |
---
GitHub Action
@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.19.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):
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.