HefestoAI

HefestoAI — AI 生成コードのリリースを検証するエンジン

English | 简体中文 | 日本語

HefestoAI は、AI アシスタントがコードを書いた後、リリースする前に実行します。プロジェクトで宣言されている内容（依存関係、設定、インストール成果物）が実際の動作と一致しているかを確認し、コード自体のセキュリティと複雑さもチェックします。

クイックスタート（GitHub Action）

エージェントが作成したコードを、決定論的に合格／不合格で判定します。 リポジトリで宣言されている内容（依存関係、README、pyproject.toml、CHANGELOG、action.yml、CI）と実際の動作を比較し、シークレットやリスクの高い IaC にフラグを立てます。同じ入力には同じ結果が返されます。

# .github/workflows/hefesto.yml
name: HefestoAI
on: [pull_request, push]
permissions:
  contents: read
  security-events: write
jobs:
  hefesto:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: artvepa80/Agents-Hefesto@v4
        with:
          fail_on: HIGH
          sarif: 'true'

検出結果は Security > Code scanning とプルリクエストのアノテーションに表示されます。公開リポジトリでは記載のとおりに動作します。GitHub Code Security が有効になっていないプライベートリポジトリでは、upload_sarif: 'false' を設定してください（SARIF ファイル自体は引き続き出力されます）。@v4 は 4.x のすべてのリリース（マイナーリリースを含む）を追跡します（4.16.0 では、解析対象のファイルがない実行はゲートで不合格になりました）。バージョンを固定するには、artvepa80/[email protected] またはコミット SHA を指定してください。この Action は hefesto analyze と同じ形式を実行します。Python に加え、YAML、Terraform、Shell、Dockerfile、SQL、PowerShell、JSON、TOML、Makefile、Groovy、COBOL、CloudFormation、ARM、Helm、Serverless、およびドリフトチェックに対応しています。TypeScript、JavaScript、Java、Go、Rust、C# を利用するには、pip install "hefesto-ai[multilang]" で CLI をインストールしてください。

無料、MIT ライセンスです。PRO（月額 8 ドル／ユーザー）と OMEGA（月額 19 ドル）：プラン。

---

運用上の整合性アナライザー（v4.20.4）

これらのアナライザーは、プロジェクトが宣言する内容と、実際に行うことの間にあるドリフトを検出します。hefesto analyze の実行ごとにチェックされます。対象となる問題は単一のファイルだけでは確認できないため、ファイル単位のリンターやセキュリティスキャナーでは報告されません。2 つのファイルを比較したときにのみ検出できます。

アナライザー	検出する問題	ルール ID
インポートと依存関係	pyproject.toml または requirements.txt に宣言されていない Python のインポート	OT-IMPORTS-001
ドキュメントとエントリーポイント	README に記載されていない [project.scripts] の CLI スクリプト	OT-DOCS-001
パッケージングの整合性	pyproject.toml、CHANGELOG、README バッジ間のバージョン不一致	OT-PKG-001/002
インストール成果物の整合性	使用されていない action.yml の入力項目、存在しない Dockerfile の COPY ソース	OT-INSTALL-001/002
CI 設定のドリフト	ローカルと CI ワークフロー間の Python バージョンまたは flake8 設定の不一致	OT-CI-001/002/003

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

---

クイックスタート

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

---

なぜ Hefesto なのか？ AI コードの問題

Claude Code、GitHub Copilot、Cursor などのアシスタントは、誰もが一行ずつレビューできる速度を超えてコードを書きます。生成されたコードの中には、リンターを通過しても危険なものがあります。

• os.system(user_input) → コマンドインジェクション
• f"SELECT * FROM {table}" → SQL インジェクション
• 実行はできても、誤記された属性や、捕捉されて破棄される例外などにより、ひそかに動作が変わるコード（Python でチェック）

Hefesto は、コードが本番環境に到達する前に問題を発見できるよう、コミット前、プッシュ前、CI でチェックします。

---

Hefesto が検出する問題

問題	重大度	説明
HARDCODED_SECRET	CRITICAL	コード内の API キー、パスワード（PostHog の phc_ や Stripe の pk_live_／pk_test_ など、既知の公開クライアントキーは LOW として報告されます）
SQL_INJECTION_RISK	HIGH	クエリ内での文字列連結
COMMAND_INJECTION	HIGH	安全でないシェルコマンドの実行
PICKLE_USAGE	HIGH	import pickle／cPickle の行（インポートが検出対象です。pickle.loads() の呼び出しは個別には報告されません）
UNDECLARED_DEPENDENCY	MEDIUM	インポートされているが、pyproject.toml に記載されていない依存関係
PACKAGING_VERSION_DRIFT	MEDIUM	pyproject／CHANGELOG／README 間のバージョンの不一致
CI_CONFIG_DRIFT	MEDIUM-HIGH	ローカル環境と CI 設定の不一致
INSTALL_ARTIFACT_DRIFT	MEDIUM-HIGH	action.yml の入力項目または Dockerfile の COPY の不一致
HIGH_COMPLEXITY	HIGH	循環的複雑度が 10 を超える
DEEP_NESTING	HIGH	ネストの深さが 4 レベルを超える
GOD_CLASS	HIGH	500 行を超えるクラス
LONG_FUNCTION	MEDIUM	50 行を超える関数
LONG_PARAMETER_LIST	MEDIUM	パラメーターが 5 個を超える関数

# 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
    with:
      target: '.'
      fail_on: 'CRITICAL'

@v4 は 4.x 系全体に追従するフローティングタグで、マイナーリリースも含まれます。すべての v4.x.y リリースでタグが更新されるため、ワークフローは編集しなくても修正を取り込めます。また、4.16.0 での変更のように、解析対象のファイルがない場合に --fail-on によって実行を失敗させる動作（終了コード 1。--allow-no-files で無効化できます）も取り込まれます。安定性を厳密に保つ必要がある場合は、artvepa80/[email protected] のような特定のリリースタグ（特定のタグは更新されません）またはコミット SHA を指定し、手動で更新してください。

GitHub code scanning への SARIF アップロードを使用する場合（検出結果は Security > Code scanning およびプルリクエストの注釈に表示されます）：

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   # SARIF needs v4.15.0 or later
        with:
          target: '.'
          fail_on: 'CRITICAL'
          sarif: 'true'

この Action はコンポジットアクションです。Action 自体のチェックアウトから HefestoAI をプライベートな仮想環境にインストールし（ランナーに python3 >= 3.10 が必要です。ubuntu-latest には含まれています）、hefesto analyze を実行します。sarif: 'true' の場合は、fail_on の条件により実行が失敗した場合も含め、github/codeql-action/upload-sarif@v4 を使って SARIF ファイルをアップロードします。詳細なリファレンスは docs/github-action.md をご覧ください。

入力：

入力	説明	デフォルト
target	解析対象のパス（ファイルまたはディレクトリ）	.
fail_on	指定した重大度以上の問題が見つかった場合、エラーで終了します	CRITICAL
allow_no_files	true の場合は --allow-no-files を渡します。そのため、解析対象ファイルがなくても、fail_on によって終了コード 0 が維持されます（意図的に空のターゲットを指定した場合）。警告は引き続き表示されます	false
allow_not_analyzed	true の場合は --allow-not-analyzed を渡します。そのため、見つかったファイルを解析できなくても、fail_on によって失敗しません。ファイルは引き続き「Not analyzed」として一覧表示され、警告も表示されます	false
min_severity	報告する最小重大度（CRITICAL、HIGH、MEDIUM、LOW）	LOW
format	ログに出力する形式（text、json、html、sarif）	text
sarif	true の場合は、SARIF 2.1.0 ファイルも書き出し、code scanning にアップロードします（security-events: write が必要です）	false
sarif_file	SARIF ファイルのパス	hefesto.sarif
upload_sarif	sarif: true の場合にファイルをアップロードします。false の場合は書き出しのみ行います	true
sarif_category	アップロードの code scanning カテゴリー	hefesto
telemetry	オプトインです。1 または true の場合のみテレメトリが有効になり、Action は実行ごとに匿名の ping を 1 回送信し、CLI は使用状況イベントを送信します。デフォルトの 0 を含め、それ以外の値ではテレメトリは送信されません（CLI は引き続き pypi.org で新しいバージョンを確認します）。docs/telemetry.md をご覧ください	0

出力：

出力	説明
exit_code	CLI の終了コード（0 = しきい値未超過、1 = fail_on のしきい値超過または実行時エラー。終了コードを参照）
sarif_file	sarif が true でファイルが書き出された場合の SARIF ファイルのパス

AI 生成コードのガードレール（Pre-commit + MCP）

HefestoAI は pre-commit チェックとして実行することも、MCP 経由で AI エージェントから呼び出すこともできるため、マージ前にリスクのある変更を検出できます。

MCP サーバーとして追加する：

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

Cursor に追加する（ワンクリック）：

ボタンを押すと、cursor.com/link 経由で Cursor のインストール確認画面が開きます（GitHub では cursor:// リンクがレンダリングされません）。直接開くディープリンク：cursor://anysphere.cursor-deeplink/mcp/install?name=hefestoai&config=eyJ1cmwiOiJodHRwczovL2hlZmVzdG9haS5uYXJhcGFsbGMuY29tL2FwaS9tY3AtcHJvdG9jb2wifQ%3D%3D。同じサーバーは、リポジトリのルートにある .mcp.json にも定義されています（{"mcpServers":{"hefestoai":{"url":"https://hefestoai.narapallc.com/api/mcp-protocol"}}}）。API キーは不要です。

API エンドポイント：

エンドポイント	プロトコル	パス
MCP	JSON-RPC 2.0	/api/mcp-protocol
ホスト型分析	HTTP POST	/api/analyze
REST	HTTP GET/POST	/api/mcp
OpenAPI	OpenAPI 3.0	/api/openapi.json
Q&A	自然言語	/api/ask
変更履歴	JSON	/api/changelog.json
FAQ	JSON	/api/faq.json

MCP の analyze ツール（および POST /api/analyze）は、送信されたファイルに対してオープンソースエンジン（hefesto analyze --no-config。ホスト型 MCP は最新の hefesto-ai リリースを実行します）を実行します。上限は 20 ファイル、各 100 KB、合計 256 KB、実行時間 20 秒です。ルール ID、重大度、行番号、SARIF フィンガープリントを含む検出結果を返します。TypeScript、JavaScript、Java、Go、Rust、C# も対象です（multilang 文法を使用。新しいサーバーインスタンスで最初にこの種のリクエストを行う際は、数秒余分にかかります）。データは保存されません。リポジトリ全体を分析するには、ローカルで hefesto analyze . を実行してください。

ホスト型 MCP サーバーはクローズドソースで、Narapa LLC が運営しています。server.json の repository は、analyze が実行するオープンソースの hefesto-ai エンジンを含むため、この公開リポジトリを参照しています。

---

PR レビュー（v4.20.4）

プルリクエストで変更されたコードのみを分析し、変更行にインラインコメントを投稿します。各検出結果には決定論的な重複排除キーが含まれているため、ワークフローでは投稿済みの検出結果をスキップできます（以下の重複排除テンプレートはこれに対応していますが、シンプルなテンプレートは対応していません）。

# 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

仕組み：

1. ベースとヘッドの間の git diff を解析します（origin/main または GITHUB_BASE_REF を自動検出します）
2. 変更対象のファイルのみで、アナライザースイート全体を実行します
3. 検出結果を変更行（デフォルト）またはファイル全体（--strict）に絞り込みます。関数単位の検出結果（複雑度、長い関数、深いネスト）は def 行に報告され、追加行が関数内にあれば変更として扱われます。line は def 行のままなので重複排除キーは変わらず、インラインコメントを付ける追加行は anchor_line に設定されます（ハンク外では null）
4. 各検出結果に SHA256 重複排除キーを付けて JSON を出力します

GitHub Actions ワークフローのテンプレートは examples/github-actions/ にあります。

テンプレート	用途	冪等性
hefesto-pr-review-simple.yml	手早い導入、小規模なリポジトリ	いいえ（再実行時に重複）
hefesto-pr-review-deduped.yml	本番 CI、チーム	はい（jq による重複排除パイプライン）

セットアップ手順については、examples/github-actions/README.md を参照してください。

---

言語サポート

コード言語

言語	パーサー	状態
Python	Native AST	完全サポート
TypeScript	TreeSitter	サポート¹
JavaScript	TreeSitter	サポート¹
Java	TreeSitter	サポート¹
Go	TreeSitter	サポート¹
Rust	TreeSitter	サポート¹
C#	TreeSitter	サポート¹

¹ TreeSitter 言語を使用するには、[multilang] エクストラが必要です： pip install "hefesto-ai[multilang]"。インストールされていない場合、これらの言語のファイルは解析時にスキップされ、Hefesto はインストールコマンドを示す警告を stderr に出力します（JSON 出力では report.meta.parser_failures からも確認できます）。

DevOps と構成

形式	アナライザー	ルール	状態	hefesto analyze による実行
YAML	YamlAnalyzer	汎用 YAML セキュリティ	v4.4.0	はい
Terraform	TerraformAnalyzer	TfSec 準拠ルール	v4.4.0	はい
Shell	ShellAnalyzer	ShellCheck 準拠	v4.4.0	はい
Dockerfile	DockerfileAnalyzer	Hadolint 準拠	v4.4.0	はい
SQL	SqlAnalyzer	SQL インジェクション対策	v4.4.0	はい
PowerShell	PS001-PS006	6 件のセキュリティルール	v4.5.0	はい
JSON	J001, J002, J004, J005	4 件のセキュリティルール	v4.5.0	はい
TOML	T001-T003	3 件のセキュリティルール	v4.5.0	はい
Makefile	MF001-MF005	5 件のセキュリティルール	v4.5.0	はい
Groovy	GJ001-GJ005	5 件のセキュリティルール	v4.5.0	はい
COBOL	CobolGovernanceAnalyzer	COBOL001-COBOL016（16 件の無料ルール）²	v4.12.0	はい

クラウドインフラストラクチャ

形式	アナライザー	対象	状態	hefesto analyze による実行
CloudFormation	CloudFormationAnalyzer	AWS IaC セキュリティ	v4.7.0	はい
ARM Templates	ArmAnalyzer	Azure IaC セキュリティ	v4.7.0	はい
Helm Charts	HelmAnalyzer	Kubernetes セキュリティ	v4.7.0	はい
Serverless	ServerlessAnalyzer	Serverless Framework	v4.7.0	はい

合計：このパッケージには、22 種類の形式に対応するアナライザーが含まれています（コード言語 7 種類 + DevOps 形式 11 種類 + クラウド形式 4 種類）。GitHub Action と pre-push フックが呼び出す hefesto analyze は、22 種類すべてを実行します。拡張子が複数の形式に該当する場合は、docs/design/devops-analyzers-wiring.md の優先順位表に従ってアナライザーが選択されます。

² COBOL：16 件のルールはすべて無料で、ライセンスは不要です。アナライザーは正規表現ベース（完全な COBOL パーサーは使用しません）で、.cbl、.cob、.cobol、.cpy、.pco ファイル（小文字または大文字）に加え、スキャン対象プログラムが COPY または EXEC SQL INCLUDE する、COBOL のデータ定義を含む .dcl、.copy、.cbk および拡張子のないファイルを読み込みます（コピーブックにはデータルール COBOL004／COBOL008／COBOL009／COBOL016、独自のネストされた COPY に対する COBOL007 と COBOL015 のみが適用され、その他のルールは適用されません）。

COBOL の詳細（ソース形式、ルールごとの動作、COPY の展開、測定された再現率、パフォーマンス、SARIF）：docs/cobol.md。

---

インストール

# 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 でインストールされるのは FREE ティアのみです。PRO または OMEGA の場合、購入後に Narapa からアクティベーションコードが送られ、コードにアクティベーション手順が付属します。

---

CLI リファレンス（v4.20.4）

# 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)

# 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 (on by default)
hefesto telemetry disable

JSON 出力

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

SARIF 出力

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

hefesto analyze が報告するすべての検出結果について、SARIF 2.1.0 を出力します（COBOL を含むすべてのアナライザーに加え、Operational Truth とプロバイダーの検出結果）。テストでは OASIS スキーマに対する検証も行います。

• ルール ID ごとに 1 つのルール（COBOL004、DOCKER010、...。アナライザーに ID がない場合は、HARDCODED_SECRET などの問題の種類）を用意し、名前、説明、ヘルプ、ヘルプ URI、デフォルトのレベルを設定します。
• level：CRITICAL／HIGH → error、MEDIUM → warning、LOW → note。セキュリティルール（シークレット、インジェクション、安全でないコマンドなど）には security-severity（9.5／8.0／5.5／3.0）も設定されるため、GitHub では Critical／High／Medium／Low として評価されます。
• CWE は 1 つのマッピング（CWE リスト 4.20）から取得します。GitHub code scanning はルールタグ external/cwe/cwe-N（ゼロ埋めなし）を読み取ります。同じ ID は run.taxonomies 内の CWE エントリー（組織 MITRE）となり、ルール上の relationships には equal、superset、relevant のいずれかが設定されます。Python：シークレット 798、SQL インジェクション 89、コマンドインジェクション 78、eval/exec 95、bare except 396、pickle のインポート 502（インポートのみが検出されるため、relevant、精度 low）。Assert には CWE がありません。検出結果の metadata.cwe はテーブルの値を上書きします。既存の COBOL タグ（cwe-798、cwe-20）はそのまま保持されます。テーブル：docs/ANALYSIS_RULES.md
• リポジトリ相対 URI（%SRCROOT%、現在のディレクトリの git トップレベル）と、ルール、ファイル、検出対象行のテキストから構築された partialFingerprints を使用するため、コード上部が移動してもアラートの ID は維持されます。
• GitHub のアップロード上限：検出結果は最大 25,000 件（重要度の高いものを優先）、gzip 圧縮後のサイズは 10 MB です。除外された項目は、ログのツール通知で報告されます。

列番号は報告されません（開始行のみ）。

フォーマットのずれ（オプトイン）

hefesto analyze はデフォルトではフォーマットをチェックしません。--format-check を指定すると、解析対象の Python ファイルに対して Black をチェックモードで実行します（プロセス内で実行し、 ファイルは変更しません）。

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

• Black で再フォーマットされるファイルごとに、重要度 LOW の FORMAT_DRIFT 検出結果が 1 件生成されます。 チェックはオプトインのため、--severity が LOW より高い場合でも これらの検出結果は表示されます。--fail-on と --exclude-types は 他の検出結果と同様に適用されるため、--fail-on MEDIUM（またはそれ以上）でフォーマットのずれが ゲート失敗になることはありません。
• Black の設定は pyproject.toml の [tool.black] テーブルから取得し、 black CLI と同じ方法で検出されます（line-length、target-version、 skip-string-normalization、preview、extend-exclude／force-exclude、...）。 required-version がインストール済みの Black と一致しない場合、Hefesto は警告します。
• JSON 出力では、code_snippet に統合差分（先頭 60 行）を含め、 metadata に lines_added／lines_removed を含めます。
• Black がインストールされていない場合、Hefesto は 1 行の警告を表示して処理を続行します。 終了コードには影響しません。
• 対象は Black のみです。isort と flake8 は実行されません。

終了コード

コード	意味
0	解析完了（--fail-on の指定がない、またはしきい値を超えていない）
1	ゲート失敗（--fail-on のしきい値を超えた、または --fail-on 指定時に解析対象のファイルがなかった）、または実行時エラー
2	コマンドラインの使用方法が無効、または .hefesto.yaml が無効

ゲートの例

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

ファイルを一つも解析しない実行（空のディレクトリ、未対応ファイルのみ、またはすべてのファイルが除外された場合）が合格として報告されることはありません。レポートには「No files were analyzed」と表示され、パスを示す警告が stderr に出力されます。また、--fail-on を指定した場合、ゲートは終了コード 1 で失敗します。ベンダー提供の JavaScript としてファイルが除外された場合、警告にはその数が示され、--include-vendored が提案されます。

意図的にファイルが空になる実行（Markdown のみを変更した PR での変更ファイルのみを対象とするジョブや、対応するソースがないモノレポのマトリックスエントリー）では、--allow-no-files を指定してください（Action の allow_no_files: 'true' 入力を指定すると、自動的にこのオプションが渡されます）。変更されるのは終了コードだけです。実行は終了コード 0 を維持し、「Gate skipped: no files were analyzed (--allow-no-files)」と表示しますが、「Files analyzed: 0」、「No files were analyzed」、および stderr の警告も引き続き出力されます。これはコマンドラインフラグのみです。.hefesto.yaml では設定できません（allow_no_files キーは不明なキーとして拒否され、終了コード 2 になります）。そのため、共有設定によってこのチェックが無効になることはありません。

UTF-8 として無効なファイルは、latin-1 のフォールバックを使って読み込まれ、解析されます（その検出結果はカウントされます）。テキストレポートでは「Decoded with fallback (latin-1)」の下に表示され、--output json では meta.decoded_with_fallback に含まれ、SARIF にはそのファイルの warning 通知が含まれます。また、stderr にも警告が出力されます。

実行によって検出されたものの解析できなかったファイル（読み取れなかった、またはそのアナライザーでエラーが発生したファイル）が、黙って除外されることはありません。テキストレポートでは理由とともに「Not analyzed」の下に表示され、--output json では meta.not_analyzed に含まれます（path、language、reason: read_error または analyzer_error、exception）。SARIF では invocations[0].toolExecutionNotifications にそのファイルの error 通知が含まれ、stderr にも警告が出力されます（--quiet の場合も同様です）。--fail-on を指定すると、「Gate failure: N file(s) could not be analyzed (exit 1)」としてゲートが失敗します。これは --allow-no-files が設定されている場合も同じです。--allow-not-analyzed（Action の allow_not_analyzed: 'true' 入力）を指定すると、この挙動を無効にできます。その場合、ゲートは検出結果のみを判定し、ファイルの一覧表示と警告は引き続き行われます。--allow-no-files と同様に、これはコマンドラインフラグのみです。

---

プッシュ前フック

ご自身のプロジェクトでは、hefesto install-hooks を実行すると、パッケージに同梱されたフックがインストールされます。pre-commit はステージングされたファイルを解析し（--fail-on HIGH）、pre-push はリポジトリを解析します（--fail-on CRITICAL）。フックは install-hooks を実行した Python インタープリター（python -m hefesto）を呼び出し、見つからない場合は PATH 上の hefesto にフォールバックします。どちらも見つからない場合はメッセージを表示して失敗します（フックを再インストールするか、SKIP_HEFESTO_HOOKS=1 を設定してください）。フックは git rev-parse --git-path hooks に配置されるため、ワークツリーやサブモジュールでも機能します。core.hooksPath が設定されている場合（Husky、lefthook など）、何も書き込まれず、コマンドは終了コード 1 で終了します。そのフックマネージャーから python -m hefesto analyze を呼び出すか、hefesto-analyze pre-commit framework フックを使用してください（pre-commit フックを参照）。フックがインストールされなかった場合も（たとえば、--force を指定せずに既存のフックがあった場合）、終了コード 1 で終了します。制限事項：pre-commit フックはステージングされたファイルの作業ツリー上のコピーを解析し、ステージングされた（インデックス上の）内容は解析しません。以下で説明する scripts/git-hooks/ のコントリビューター向けフックは、Agents-Hefesto のクローン（ルートの pyproject.toml に name = "hefesto-ai" と記載）でのみ使用されます。どちらのフックセットをインストールしたかは、コマンドの出力で確認できます。

このリポジトリでは、git push のたびに検証が自動実行されます。

# Install the same hooks and print the plans link (PRO $8/mo, OMEGA $19/mo)
hefesto init

# 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

このフックでは、2 つのゲートが実行されます。

1. セキュリティゲート — hefesto analyze に --fail-on CRITICAL --exclude-types VERY_HIGH_COMPLEXITY,LONG_FUNCTION を指定します（セキュリティ上の問題をブロックし、複雑さに関する負債は無視します）。
2. 高速な lint／テストゲート — Black、isort、Flake8、および最小限のテストスイート

注： フックはローカル環境にのみ設定され、Git にコミットされません。クローン後、または scripts/git-hooks/pre-push が更新されたときは、hefesto install-hooks を実行してください。

---

プラン別機能

機能	FREE	PRO（ユーザーあたり月額 $8）	OMEGA（月額 $19）
静的解析	あり	あり	あり
セキュリティスキャン	基本	高度	高度
プッシュ前フック	あり	あり	あり
言語とフォーマットのサポート（詳細）	あり	あり	あり
ML による強化	なし	あり	あり
REST API	なし	あり	あり
IRIS モニタリング	なし	なし	あり
本番環境との相関分析	なし	なし	あり

• PRO（ユーザーあたり月額 $8）および OMEGA（月額 $19）：プランと購入手続き

Hefesto PRO のオプション機能

Hefesto OSS は単独で動作します。Hefesto PRO がインストールされている場合、OSS ではオプションで次の機能を有効にできます。 hefesto serve の Patch C API の強化、スコープゲーティング（デフォルトではファーストパーティのみ）、TS/JS シンボルの検出、および安全で決定論的なエンリッチメント（スキーマ優先、マスク処理、範囲制限あり）。 docs/PRO_OPTIONAL_FEATURES.md を参照してください。

---

REST API（PRO）、OMEGA Guardian、IRIS

hefesto serve（PRO）は、アナライザーを HTTP 経由で公開します：docs/rest-api.md。OMEGA Guardian と IRIS 本番環境モニタリングエージェントについては、docs/omega-iris.md を参照してください。

---

CI/CD 統合

GitHub Actions — リポジトリ全体の解析

name: Hefesto

on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Hefesto
        run: pip install hefesto-ai
      - name: Run Analysis
        run: hefesto analyze . --severity HIGH

GitHub Actions — CLI によるコードスキャン（SARIF）

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - run: pip install hefesto-ai
      - run: hefesto analyze . --severity LOW --fail-on CRITICAL --sarif-file hefesto.sarif
      - if: always()
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: hefesto.sarif
          category: hefesto

GitHub Actions — インラインコメント付き PR レビュー（v4.20.4）

name: Hefesto PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: pip install hefesto-ai
      - name: Review changed code
        env:
          GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref }}
          GITHUB_SHA: ${{ github.event.pull_request.head.sha }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: hefesto pr-review --post --pr ${{ github.event.pull_request.number }} --repo ${{ github.repository }}

本番環境で重複排除を使用する場合（再実行時にコメントが重複しないようにする場合）は、examples/github-actions/ のワークフローテンプレートを参照してください。

pre-commit フック

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/artvepa80/Agents-Hefesto
    rev: v4.20.4
    hooks:
      - id: hefesto-analyze

GitLab CI

hefesto:
  stage: test
  script:
    - pip install hefesto-ai
    - hefesto analyze . --severity HIGH

---

設定

hefesto analyze は、コマンドラインフラグ（上記の CLI リファレンスを参照）からオプションを取得し、必要に応じて（以下の）.hefesto.yaml ファイルからも取得します。重大度や出力形式などの解析オプションに対応する環境変数はありません。

環境変数

# 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 auth
export HEFESTO_RATE_LIMIT_PER_MINUTE=60               # Enable rate limiting
export HEFESTO_CORS_ORIGINS="https://app.example.com" # Restrict CORS
export HEFESTO_EXPOSE_DOCS=1                          # Enable /docs, /redoc
export HEFESTO_WORKSPACE_ROOT="/srv/code"              # Path sandbox root
export HEFESTO_CACHE_MAX_SIZE=1000                     # Cache size limit
export HEFESTO_CACHE_TTL_SECONDS=300                   # Cache entry TTL

設定ファイル（.hefesto.yaml）

実行のたびに繰り返し指定する代わりに、hefesto analyze のオプションを .hefesto.yaml（または .hefesto.yml）ファイルに記述します。通常はリポジトリのルートに配置します。

# .hefesto.yaml -- every key is optional and maps to a `hefesto analyze` flag
severity: MEDIUM            # --severity      LOW | MEDIUM | HIGH | CRITICAL
fail_on: HIGH               # --fail-on       LOW | MEDIUM | HIGH | CRITICAL
output: text                # --output        text | json | html
exclude:                    # --exclude       list or "a/,b/" string
  - tests/
  - node_modules/
exclude_types:              # --exclude-types list or comma-separated string
  - VERY_HIGH_COMPLEXITY
  - LONG_FUNCTION
quiet: false                # --quiet
max_issues: 50              # --max-issues
format_check: true          # --format-check  (needs: pip install "hefesto-ai[format]")
enable_memory_budget_gate: false  # --enable-memory-budget-gate
copybook_paths:             # --copybook-path (COBOL copybook directories outside the scan)
  - ../copylib              # relative paths are resolved from this file's directory
include_vendored: false     # --include-vendored (analyze vendored/minified JavaScript too)

• デフォルトで除外： .venv/、venv/、.tox/、node_modules/、 .git/、__pycache__/、dist/、build/、.mypy_cache/、 .pytest_cache/、.eggs/、*.egg-info/（解析対象パス内のパス構成要素全体）。さらに、ベンダー提供の JavaScript と圧縮済み JavaScript（.js、.mjs、 .cjs）：*.min.js／*-min.js ファイル、vendor/、vendors/、 bower_components/ または jspm_packages/ 内のファイル、ならびに static/、assets/、public/ または wwwroot/ 内の lib/、libs/、plugins/、third_party/、thirdparty/ ディレクトリ内のファイル（例：static/js/libs/jquery.js）。 トップレベルの lib/ はプロジェクト独自のコードとして対象に含まれます。また、vendor/ 内の JavaScript 以外のファイル（Go、PHP）も対象に含まれます。--include-vendored（または include_vendored: true）を指定すると、JavaScript ファイルも再び解析されます。コマンドラインで指定した単一ファイルは常に解析されます。 サマリーには、除外されたファイル数が表示されます（N files skipped as vendored (use --include-vendored)。JSON では meta.vendored_skipped、SARIF ではツールの通知に表示されます）。

• critical_tests（プレビュー）： クリティカルテストの回帰ガードで要件と pytest テストを対応付ける任意のセクションです。hefesto analyze はこのセクションを検証しますが、それ以外の用途には使いません。詳しくは docs/critical-tests.md を参照してください。

• exclude の項目はパスセグメントであり、グロブではありません。 各項目は解析対象パス内のパス構成要素全体に一致します（tests/fixtures/ は tests/fixtures/... を除外します）。* と ** は文字どおりに扱われるため、 tests/fixtures/** や *.json は、"Excluding: ..." に表示されても何にも一致しません。コマンドラインで明示的に指定したファイルやディレクトリは、 exclude によるフィルタリングの対象になりません。

• 検出： Hefesto は hefesto analyze に指定された最初のパスから開始し（ファイルの場合はそのディレクトリ）、リポジトリのルート（.git を含む最初のディレクトリ）まで、またはリポジトリ外ではファイルシステムのルートまでさかのぼって検索します。最も近いファイルが優先されます。同じディレクトリに .hefesto.yaml と .hefesto.yml の両方がある場合はエラーになります。複数のパスを指定した場合、最初のパスの設定が実行全体に適用されます（別のパスで異なるファイルが選ばれる場合、Hefesto は警告します）。

• 優先順位： 明示的なフラグ > 設定ファイル > 組み込みのデフォルト値。デフォルト値と同じ値を指定した場合も、フラグは明示的な指定として扱われます（--severity MEDIUM は severity: LOW を上書きします）。リストはマージではなく置き換えられます： --exclude docs/ を指定すると、ファイル内の exclude は無視されます。

• フラグ： --config PATH は検索の代わりに指定したファイルを使います。 --no-config は設定ファイルを無視します。両方を同時に指定することはできません。

• 検証： 不明なキー、不正な値、無効な YAML がある場合、問題を示すメッセージと終了コード 2 で実行が停止します。例： Error: invalid Hefesto config in /repo/.hefesto.yaml: 'severity' must be one of LOW, MEDIUM, HIGH, CRITICAL (got 'urgent')。 キーには - または _ を使用できます（fail-on または fail_on）。null は「未設定」を意味します。

• 使用中のファイルは Config: <path> として表示されます（--output json の場合は stderr に出力され、--quiet では表示されません）。

• このファイルを読み込むのは hefesto analyze のみです（pr-review や GitHub Action の入力では読み込まれません）。ルールのしきい値（循環的複雑度など）、--save-html、PRO のスコープ／エンリッチメント用フラグは、このファイルでは設定できません。

---

競合製品との比較

基準	Hefesto	Semgrep	CodeRabbit	Qodo	Snyk
AI 生成コードへの注力	✅ 主なユースケース	汎用	✅ はい	✅ はい	汎用
宣言内容と実態のドリフト検出	✅ 中核機能	❌	❌	❌	❌
運用実態の真偽を検証するアナライザー	✅ 5 つのアナライザー	❌	❌	❌	❌
対応言語	CLI で 22 種類の形式を解析（詳細）	多数	多数	多数	多数
セットアップ時間	5 分未満、設定不要	設定が多い	クラウドへの登録	クラウドへの登録	クラウドへの登録
実行場所	ローカル CLI／GitHub Action／pre-commit／MCP	ローカル／クラウド	クラウドのみ	クラウドのみ	クラウド／CLI
料金（2026 年 10 月現在）	無料 OSS／月額 $8 PRO／月額 $19 OMEGA	無料プラン／Teams はコード担当者 1 人あたり月額 $30*	パブリックリポジトリは無料／開発者 1 人あたり月額 $24（年払い）	クレジット制、1 クレジットあたり $0.012。恒久的な無料プランなし	無料／Team は月額 $25**

*Semgrep Supply Chain と Secrets は別料金です。 **Snyk Team は開発者 10 人まで対応し、Enterprise はクレジット制です。料金は各ベンダーの公式料金ページを 2026 年 10 月に確認したものです。料金は頻繁に変更されます。

HefestoAI の位置づけ： ほとんどのツールは、コードをその言語のルールに照らしてチェックします。HefestoAI はさらに、プロジェクト内の宣言内容と実態もチェックします。インポートが宣言された依存関係と一致しているか、pyproject.toml、CHANGELOG、README に記載されたバージョンが一致しているか、action.yml と Dockerfile が参照先のファイルと一致しているかを確認します。

---

ドッグフーディング（率直な報告）

main へのプッシュごとに、HefestoAI 自身のコードに対して HefestoAI の strict gate を実行しています。ゲートは 2026-04-29 以降 GREEN ですが、そこに至るまでには 6 週間以上かかりました。指摘事項を記録したのは 2026-03-17 です。

strict モードでは、自分たちの gate-internals コードで複雑さに関する指摘が 12 件検出されました（CRITICAL が 2 件、HIGH が 10 件）。対応策として、指摘を黙殺する（却下。まさに批判しているドリフトに当たるため）、オーバーライドを恒久的に受け入れる（却下。同じ理由のため）、根本原因をリファクタリングする（採用）の 3 つを検討しました。着手後の根本原因のリファクタリング自体は短期間で完了しました。1 つの PR を 2 日間（2026-04-27 と 04-28）で作成し、2026-04-29 にマージしました。その過程で、自社のポジショニング文書に宣言内容と実態のドリフトがあることも見つけ、修正のために記録しました。

監査とリファクタリングの全履歴は、非公開リポジトリで社内管理しています。リファクタリングにより、2 つの CRITICAL 関数の循環的複雑度は 33 → 1、25 → 6 となり、すべてのヘルパー関数が 10 未満になりました。10 件の HIGH 指摘には一時的なオーバーライドを適用しており、その仕組みと取り消し基準を文書化しています。

---

テレメトリー

CLI はデフォルトで、匿名の利用イベントを PostHog に送信します（ランダム ID。analyze はファイル数と指摘件数、処理時間、終了コード、バージョン、OS、Python、ci/docker/dogfood に加え、pypi または editable も送信します。コード、ファイルパス、指摘の内容、リポジトリ名は送信せず、ペイロードに IP フィールドはありません）。hefesto telemetry disable、HEFESTO_TELEMETRY=0、または DO_NOT_TRACK=1 で無効にできます。GitHub Action は、telemetry: 1 を設定しない限り利用イベントを送信しません。これとは別に、hefesto analyze は最新バージョンを pypi.org に問い合わせます（タイムアウトは 1.5 秒、24 時間キャッシュ）。hefesto telemetry disable では、この確認は停止しません。4.20.3 以降では以下の設定で確認をスキップできます。4.20.2 以前には無効化する設定はありません。詳細：docs/telemetry.md。

HEFESTO_NO_UPDATE_CHECK が 1、true、yes、on のいずれかの場合、HEFESTO_TELEMETRY が 0、false、no、off のいずれかの場合、または DO_NOT_TRACK が 1、true、yes、on のいずれかの場合、PyPI の新バージョン確認はリクエストもキャッシュへの書き込みも行わずにスキップされます。利用イベントはデフォルトで有効です。Action のデフォルト値 telemetry: 0 は HEFESTO_TELEMETRY=0 を設定するため、ランナーではこの確認は実行されません。

変更履歴

リリース履歴：CHANGELOG.md。

---

お問い合わせ

• 法人向けおよびライセンスに関するお問い合わせ：[email protected]
• サポートおよびバグ報告：[email protected]
• 一般的なお問い合わせ：[email protected]
• GitHub Issues：artvepa80/Agents-Hefesto/issues
• ウェブサイト：hefestoai.narapallc.com

ライセンス

このリポジトリのコードは、MIT Licenseのもとでライセンスされています。有料のPROおよびOMEGA機能（別途配布されるhefesto_proアドオン）は、LICENSE-COMMERCIAL.mdに記載された別個の商用条件の対象となります。ライセンスに関するお問い合わせ：[email protected]。

---

(c) 2026 Narapa LLC, Miami, Florida