hefestoai-auditor

name	hefestoai-auditor
version	2.1.0
description	AI-powered architectural guardian with Socratic Adaptive Constitution. Runs security audits, detects semantic drift, analyzes complexity, and prevents AI-generated code degradation across 17 languages. Governed by formal ethical principles and multi-model awareness.
metadata	{"openclaw":{"emoji":"🔨","requires":{"bins":["hefesto"]},"install":[{"id":"pip","kind":"pip","package":"hefesto-ai","bins":["hefesto"],"label":"Install HefestoAI (pip)"}]}}

HefestoAI Auditor Skill v2.0

AI-powered architectural guardian. Not just a code analyzer — a security and quality governance system governed by a Socratic Adaptive Constitution.

What's New in v2.0

• Constitución Socrática Adaptativa: Formal ethical framework governing all bot behavior
• Semantic Drift Detection: Identifies when AI-generated code subtly alters logical intent
• Multi-Model Architecture (Active): Grok, DeepSeek, Claude, and OpenAI integrated as operational sub-agents
• Enhanced Security Posture: Explicit security scope definition and continuous audit principle
• Optimized Token Management: Structured outputs and delta-based communication

---

Quick Start

Run a full audit

source /home/user/.hefesto_env 2>/dev/null
hefesto analyze /absolute/path/to/project --severity HIGH --exclude venv,node_modules,.git

Severity levels

hefesto analyze /path --severity CRITICAL   # Critical only
hefesto analyze /path --severity HIGH        # High + Critical
hefesto analyze /path --severity MEDIUM      # Medium + High + Critical
hefesto analyze /path --severity LOW         # Everything

Output formats

hefesto analyze /path --output text                          # Terminal (default)
hefesto analyze /path --output json                          # Structured JSON
hefesto analyze /path --output html --save-html report.html  # HTML report
hefesto analyze /path --quiet                                # Summary only

Status and version

hefesto status
hefesto --version

---

Socratic Adaptive Constitution (Summary)

This skill operates under a formal constitution with 6 chapters:

1. Fundamental Principles: Truthfulness, human leadership, continuous audit, beneficence, accountability, privacy
2. Socratic Adaptive Method (MSA): 4-phase workflow — Diagnose, Decide (max 2 questions), Execute (minimal impact), Verify
3. Multi-Model Architecture: Current Gemini + future DeepSeek/Claude Code/Grok roles
4. Security: Shift-left code/config vulnerabilities (not runtime/network)
5. Operational Rules: Anti-spam, anti-hallucination, structured responses
6. Capabilities: Audit protocol, social publishing, dev tools

Full constitution: see workspace CLAUDE.md

---

What It Detects

Security Vulnerabilities

• SQL injection and command injection
• Hardcoded secrets (API keys, passwords, tokens)
• Insecure configurations (Dockerfiles, Terraform, YAML)
• Path traversal and XSS risks

Semantic Drift (AI Code Integrity)

• Logic alterations that preserve syntax but change intent
• Architectural degradation from AI-generated code
• Hidden duplicates and inconsistencies in monorepos

Code Quality

• Cyclomatic complexity >10 (HIGH) or >20 (CRITICAL)
• Deep nesting (>4 levels)
• Long functions (>50 lines)
• Code smells and anti-patterns

DevOps Issues

• Dockerfile: missing USER, no HEALTHCHECK, running as root
• Shell: missing set -euo pipefail, unquoted variables
• Terraform: missing tags, hardcoded values

What It Does NOT Detect

• Runtime network attacks (DDoS, port scanning)
• Active intrusions (rootkits, privilege escalation)
• Network traffic monitoring
• For these, use SIEM/IDS/IPS or GCP Security Command Center

---

Supported Languages (17)

Code: Python, TypeScript, JavaScript, Java, Go, Rust, C# DevOps/Config: Dockerfile, Jenkins/Groovy, JSON, Makefile, PowerShell, Shell, SQL, Terraform, TOML, YAML

---

Interpreting Results

📄 <file>:<line>:<col>
├─ Issue: <description>
├─ Function: <name>
├─ Type: <issue_type>
├─ Severity: CRITICAL | HIGH | MEDIUM | LOW
└─ Suggestion: <fix recommendation>

Issue Types

Type	Severity	Action
VERY_HIGH_COMPLEXITY	CRITICAL	Fix immediately
HIGH_COMPLEXITY	HIGH	Fix in current sprint
DEEP_NESTING	HIGH	Refactor nesting levels
SQL_INJECTION_RISK	HIGH	Parameterize queries
HARDCODED_SECRET	CRITICAL	Remove and rotate
LONG_FUNCTION	MEDIUM	Split function

---

Pro Tips

# CI/CD gate - fail build on issues
hefesto analyze /path --fail-on HIGH --exclude venv

# Pre-push hook
hefesto install-hook

# Limit output
hefesto analyze /path --max-issues 10

# Exclude specific types
hefesto analyze /path --exclude-types VERY_HIGH_COMPLEXITY,LONG_FUNCTION

Wrapper Script (Recommended)

#!/bin/bash
source /home/user/.hefesto_env 2>/dev/null
exec hefesto "$@"

---

Multi-Model Architecture (Active)

HefestoAI Auditor is designed to work within a 4-model system:

Model	Role	Status
Gemini 2.5 Flash	Central brain + ethical filter	Active
DeepSeek	Logical architect (formalization)	Active
Claude Code	Senior coder (generation + refactoring)	Active
Grok	Strategist + social sensor (X/Twitter)	Active
OpenAI GPT	Complementary analyst	Active

HefestoAI acts as the external audit layer — reviewing output from all models for security and quality compliance.

Multi-Model Commands

# Query individual models
source ~/.hefesto_env 2>/dev/null
python3 ~/hefesto_tools/multi_model/query_model.py --model grok "Analyze trends"
python3 ~/hefesto_tools/multi_model/query_model.py --model deepseek "Formalize this algorithm"
python3 ~/hefesto_tools/multi_model/query_model.py --model claude "Review this code"

# Run constitutional pipelines
python3 ~/hefesto_tools/multi_model/orchestrate.py --task code-review --input "def foo(): ..."
python3 ~/hefesto_tools/multi_model/orchestrate.py --task full-cycle --input "Design a webhook validator"
python3 ~/hefesto_tools/multi_model/orchestrate.py --task strategy --input "Position vs Devin"

---

Licensing Tiers

Tier	Price	Key Features
FREE	$0/mo	Static analysis, 17 languages, pre-push hooks
PRO	$8/mo	ML semantic analysis, REST API, BigQuery, custom rules
OMEGA	$19/mo	IRIS monitoring, auto-correlation, real-time alerts, team dashboard

All paid tiers include a 14-day free trial.

• PRO: https://buy.stripe.com/4gM00i6jE6gV3zE4HseAg0b
• OMEGA: https://buy.stripe.com/14A9AS23o20Fgmqb5QeAg0c

export HEFESTO_LICENSE_KEY=<your-key>
hefesto status  # verify tier

---

Important Rules

• ALWAYS use absolute paths, never . or relative paths
• ALWAYS load environment first: source /home/user/.hefesto_env
• ALWAYS exclude: --exclude venv,node_modules,.git
• REPORT ONLY what hefesto returns — never invent or add issues

---

About

Created by Narapa LLC (Miami, FL) — Arturo Velasquez (@artvepa) GitHub: https://github.com/artvepa80/Agents-Hefesto Support: [e-mail]

"El código limpio es código seguro" 🛡️