{
  "markdown": "<div align=\"center\">\n\n<img src=\"./logo.svg\" alt=\"Auditor Addon Logo\" width=\"400\">\n\n### *The LLM Multi Tool for Code Auditing*\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Zig](https://img.shields.io/badge/Zig-0.15+-F7A41D?logo=zig&logoColor=white)](https://ziglang.org/)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-6B48FF?logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)\n[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-Extension-4285F4?logo=google&logoColor=white)](https://github.com/google-gemini/gemini-cli)\n[![Cursor](https://img.shields.io/badge/Cursor-Compatible-000000?logo=cursor&logoColor=white)](https://cursor.sh)\n[![Windsurf](https://img.shields.io/badge/Windsurf-Compatible-0B100F?logo=windsurf&logoColor=white)](https://codeium.com/windsurf)\n[![Codex](https://img.shields.io/badge/OpenAI_Codex-Compatible-412991?logo=openai&logoColor=white)](https://openai.com/codex)\n\n**Skills and a CLI for code estimation, security auditing, and professional report writing. Works with any AI coding environment.**\n\n</div>\n\n## 🎯 Skills\n\nSkills are structured workflows that guide the AI through multi-step processes. Each skill contains detailed instructions, phases, and best practices for specific tasks.\n\n| Skill | Purpose | Capabilities |\n|:------|:--------|:-------------|\n| 🛡️ **security-auditor** | Interactive security auditing with Map & Probe methodology | Map (structural inventory) → Checklist (optional, standard-specific) → Probe (per-path vulnerability analysis) |\n| 🔍 **threat-modeling** | Systematic threat enumeration before code-level auditing | Analyze → Diagram → Attackers → Assets → Threats (STRIDE) → Report |\n| 📊 **estimator** | Project scoping and effort estimation | Full scope (Discovery, Explore, Metrics, Report) or Diff scope (Discovery, Review, Report) |\n| 🧠 **design-challenger** | Challenge overcomplicated designs | Propose simplifications with explicit trade-offs |\n| 📝 **scribe** | Report writing and finding generation | Professional issue descriptions, report introductions |\n| 🔬 **sast-pipeline** | Run the SAiST static analysis pipeline | Init scan → Resolve gaps → Run rules (shipped + custom) |\n| ✏️ **rule-authoring** | Author SAiST detection rules | Scope, deep, and map rule types with testing patterns |\n\n### How Skills Work\n\nSkills provide complete workflows that the AI follows autonomously. When invoked, the AI loads the skill's protocol and executes it step-by-step, using the available tools as needed. Each skill can be invoked through its respective slash command (e.g., `/security-auditor`, `/estimator`).\n\n> [!NOTE]\n> **Model Performance**: Skills perform differently across AI models. Depending on your needs, you may want to adjust the model for optimal results:\n> \n> - **Speed**: Lighter models (e.g., Claude Haiku, Gemini Flash) execute faster but may miss subtle issues\n> - **Reasoning Effort**: More capable models (e.g., Claude Sonnet/Opus, Gemini Pro) provide deeper analysis and better edge case detection\n> - **Thoroughness**: Higher-tier models tend to be more comprehensive in their exploration and validation\n> - **Verbosity**: Models with higher reasoning capabilities can be less verbose in their thinking process\n>\n> Experiment with different models to find the right balance for your use case.\n\n---\n\n## 🧰 CLI Tools\n\nThe `aud` CLI provides structured code analysis through tree-sitter AST parsing. All commands support glob patterns for analyzing multiple files at once (e.g., `\"src/**/*.sol\"`). Skills invoke these commands automatically as part of their workflows. Output uses TOON by default; pass `--json` for JSON.\n\n### 👀 `aud peek`\n\nExtracts function and method signatures from source files without reading full implementations. The **estimator** skill uses peek to quickly understand a codebase's API surface, what functions exist, their parameters, visibility, and modifiers. This is ideal for initial exploration and building a mental map of unfamiliar code, without the need to read full files.\n\n### 📏 `aud metrics`\n\nCalculates code metrics:\n\n- **Normalized Lines of Code (nLOC)**: Total lines minus blank lines, comment-only lines, and multi-line constructs normalized to single lines (e.g., a function signature spanning 3 lines counts as 1).\n- **Comment Density**: Percentage of lines that have/are comments, indicating documentation coverage.\n- **Cognitive Complexity**: Measures control flow complexity by counting branches (if, for, while, etc.) weighted by nesting depth. Deeply nested logic scores higher than flat code.\n- **Estimated Hours**: Review time estimate based on nLOC and a per-language base rate.\n\nThe **estimator** skill uses this command to calculate how long it takes to perform a security audit.\n\n### 📈 `aud diff-metrics`\n\nMetrics restricted to lines changed between two git refs. Shells out to `git diff -U0 -M` to extract added/removed line ranges per file, then parses each changed file with tree-sitter and computes the same metrics as `aud metrics` — restricted to added lines for `nloc_added` and `complexity_added`, and to removed lines for `nloc_removed`.\n\nComplexity follows SPEC-CLI §2.2 semantics: a new branch node adds `1 + branching_ancestors` (including pre-existing ancestors). Non-branch added lines contribute zero complexity.\n\nEach row also emits `changed_functions` — the names of head-tree callables whose bodies overlap ≥1 *surviving* added line (blank/comment/test-only changes don't list the function). Feed these straight into `aud call-chains --root=<name>` for reach analysis.\n\nThe **estimator** skill uses this command for incremental audit scoping (sizing a PR before review).\n\n### 🔗 `aud gaps`\n\nBuilds a symbol graph (containers, callables, variables, events, modifiers, edges) from source files and outputs unresolved **edge gaps** — references the static pass cannot resolve (unresolved callees, interface dispatch, external libraries). Gaps are prioritized by edge kind (high/medium/low) for agent triage.\n\nSupports `--resolutions=<file>` to apply a CSV of manually resolved gaps, promoting them to concrete edges.\n\n### ⛓️ `aud call-chains`\n\nTraces call chains from root functions (callables with no incoming call edges) through the full call graph, grouped by root and sorted longest-first. The **security-auditor** skill uses this to understand how execution flows through a system and to identify attack surfaces.\n\nSupports `--root=<name>` to start from specific functions, and `--max-depth=<n>` to limit traversal depth.\n\n### 📊 `aud graph`\n\nBuilds and dumps the full symbol graph — all nodes (files, containers, callables, variables, modifiers, events) and edges (contains, calls, reads, writes, has_modifier, inherits, emits, imports). Useful for inspecting the graph structure directly.\n\n### 🔬 `aud run` — Rules Engine\n\nBuilds the symbol graph and runs Lua-based detection rules against it. Rules are either shipped (built-in) or custom (`.lua` files).\n\n- `--rule=<ID>` — run specific shipped rule(s) only\n- `--rule-path=<path>` — run an adhoc rule from a `.lua` file\n- `--rule-inline=<lua>` — run an adhoc rule from an inline Lua string\n\nFindings include rule metadata, confidence, location, and optional execution paths for deep rules. Supports filtering by confidence level (issue, smell, pointer).\n\n### ℹ️ `aud info`\n\nLists language config details (container types, callable types, variable types, visibility extraction, builtin filters, metrics config). Useful for understanding what the parser sees for a given language.\n\n### 🌐 Supported Languages\n\n<div align=\"center\">\n\nSolidity · Rust · Go · Python · Cairo · Compact · Move · Noir · Tolk · Masm · C++ · Java · JavaScript · TypeScript · TSX · Flow\n\n</div>\n\n## 📦 Installation\n\n### Via Claude Code Plugin\n\n```bash\n# 1. Start Claude Code\nclaude\n\n# 2. Go to plugins\n/plugin\n\n# 3. Navigate to Marketplaces tab\n# 4. <enter> on \"+ Add Marketplace\"\n# 5. Paste this repo's link, <enter>\n# 6. Hit <space> and <i>\n```\n\n### Via Gemini CLI Extension\n\n```bash\ngemini extensions install <repository-url>\n```\n\n### Other AI Coding Environments (Cursor, Codex, Windsurf, etc.)\n\nSkills can be installed using the [skills CLI](https://skills.sh/). This includes the `aud` CLI — pre-built binaries for all platforms are shipped with the `auditor-addon-cli` skill:\n\n```bash\nnpx skills add <repository-url>\n```\n\nThe AI can invoke `aud` directly via the skill path. For manual use, see the `auditor-addon-cli` skill's SKILL.md for instructions on adding `aud` to your PATH.\n\n### Building from Source\n\nRequires [Zig 0.15+](https://ziglang.org/download/).\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd auditor-addon\n\n# Native build\nzig build\n\n# Run tests\nzig build test\n\n# Cross-compile all platforms (macOS/Linux/Windows × arm64/x86_64)\n./scripts/build-all.sh --release\n```\n\n---\n\n## 🏗️ Architecture & Design\n\n### Core Principles\n\n- 🧩 Modular: Clear separation between CLI, pipeline, language configs, and output\n- 🔌 Extensible: Add new languages via declarative `LanguageConfig` structs\n- ⚡ Fast: Single Zig binary, zero runtime dependencies, tree-sitter grammars compiled in\n- 🔬 Rules in Lua: Detection rules are authored in Lua, loaded at runtime\n\n### Technology Stack\n\n- **Language**: ![Zig](https://img.shields.io/badge/Zig-0.15+-F7A41D?logo=zig&logoColor=white) — single binary, cross-compiles to all platforms\n- **AST Engine**: [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) — grammars compiled into the binary\n- **Rules Engine**: [Lua](https://www.lua.org/) — embedded via ziglua\n- **Output Format**: [TOON](https://github.com/toon-format/toon) — Token-Oriented Object Notation (or JSON)\n- **CLI Parsing**: [zig-clap](https://github.com/Hejsil/zig-clap)\n\n### Key Project Files\n\n- [`.claude-plugin/`](./.claude-plugin/): 🔌 Claude Code plugin configuration\n- [`CLAUDE.md`](./CLAUDE.md): 🤖 Claude Code plugin context guide\n- [`GEMINI.md`](./GEMINI.md): 🤖 Gemini CLI extension context guide\n- [`gemini-extension.json`](./gemini-extension.json): ⚙️ Gemini CLI extension configuration\n- [`skills/`](./skills/): 🎯 Skill definitions and protocols\n- [`src/`](./src/): 🔧 Zig source (pipeline, language configs, output, CLI)\n- [`vendor/grammars/`](./vendor/grammars/): 🌳 Tree-sitter grammar sources\n- [`skills/auditor-addon-cli/bin/`](./skills/auditor-addon-cli/bin/): 📦 Pre-built binaries + platform dispatcher\n",
  "bytes": 10485,
  "sha": "d5a8f4c82bbc2f9eff3929575c7da34b1783556793113a078aa3bb0e0f89abab",
  "repo_slug": "artifex1/auditor-addon",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_artifex1_auditor_addon_53e52d80/readme"
}