{"id":51756495,"url":"https://github.com/falcoraxyz/mincode-vuln-arch","last_synced_at":"2026-07-19T07:03:32.590Z","repository":{"id":370753713,"uuid":"1296754231","full_name":"Falcoraxyz/mincode-vuln-arch","owner":"Falcoraxyz","description":"Minimal code generator + vuln auditor + architecture miner with a local HMAC-signed hash-chain Obsidian vault. Zero-dep, Hermes skill.","archived":false,"fork":false,"pushed_at":"2026-07-10T19:09:17.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-10T19:16:40.672Z","etag":null,"topics":["cli-tool","code-generation","hermes","knowledge-base","obsidian","python","security","static-analysis"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Falcoraxyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-10T17:38:15.000Z","updated_at":"2026-07-10T19:09:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Falcoraxyz/mincode-vuln-arch","commit_stats":null,"previous_names":["falcoraxyz/mincode-vuln-arch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Falcoraxyz/mincode-vuln-arch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Falcoraxyz%2Fmincode-vuln-arch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Falcoraxyz%2Fmincode-vuln-arch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Falcoraxyz%2Fmincode-vuln-arch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Falcoraxyz%2Fmincode-vuln-arch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Falcoraxyz","download_url":"https://codeload.github.com/Falcoraxyz/mincode-vuln-arch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Falcoraxyz%2Fmincode-vuln-arch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35644213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli-tool","code-generation","hermes","knowledge-base","obsidian","python","security","static-analysis"],"created_at":"2026-07-19T07:03:29.099Z","updated_at":"2026-07-19T07:03:32.582Z","avatar_url":"https://github.com/Falcoraxyz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐦 mincode-vuln-arch\n\n\u003e **Ship the least code needed. Modular. Audited. Remembered.**\n\u003e One toolkit, five ways to call it — from any AI agent or the CLI.\n\n`mincode-vuln-arch` generates **minimal, modular, human-style code from scratch**,\n**audits every project** for vulnerabilities, **mines clean architecture** from\nreal repos into reusable templates, and **persists findings** into a\ntamper-evident **local hash-chain vault** (Obsidian optional).\n\n**Zero external runtime dependencies** — everything runs on the Python standard\nlibrary. Optional `bandit` / `pip-audit` / an LLM key deepen coverage.\n\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org)\n[![Zero deps](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#)\n[![MCP](https://img.shields.io/badge/MCP-ready-purple.svg)](#as-an-mcp-server)\n[![AgentSkills](https://img.shields.io/badge/AgentSkills-compatible-green.svg)](#agent-agnostic)\n[![CI](https://github.com/Falcoraxyz/mincode-vuln-arch/actions/workflows/audit.yml/badge.svg)](https://github.com/Falcoraxyz/mincode-vuln-arch/actions)\n[![Repo size](https://img.shields.io/github/repo-size/Falcoraxyz/mincode-vuln-arch)](https://github.com/Falcoraxyz/mincode-vuln-arch)\n\n---\n\n## ✨ Features\n\n| #  | Capability            | Script            | What it does |\n|----|-----------------------|-------------------|--------------|\n| 1  | **Scaffold**          | `proj_gen.py`     | Minimal modular skeleton (`src/ tests/ docs/`), stdlib-first. Auto `git init` + `scaffold-\u003cdate\u003e` tag. |\n| 2  | **Audit**             | `audit.py`        | Heuristic vuln scan (+ optional `bandit`). CWE-tagged, A–F grade, dependency CVE scan (`pip-audit`). |\n| 2b | **SARIF export**      | `audit.py`        | `--sarif out.sarif` (2.1.0) for GitHub code scanning; auto-uploaded by CI. |\n| 2d | **HTML report**       | `audit.py`        | `--report out.html` (self-contained: severity colors, CWE links, grade badge). |\n| 3  | **Mine architecture** | `sample_repo.py`  | Extract clean module boundaries + reusable snippets from any repo (human or AI-authored). |\n| 3b | **Multi-language**    | `audit.py`        | Polyglot heuristic scan: Python + JS/TS/Go/Rust/sh, CWE-tagged. |\n| 3c | **Arch auto-apply**   | `sample_repo.py`  | `--apply-arch` appends missing Architecture-Decision rows to `SKILL.md`. |\n| 4  | **Gen tests**         | `gen_tests.py`    | `ast`-based generation — typed dummy args + `isinstance` assertions from return annotations. Zero-dep `unittest`. |\n| 5  | **Hash-chain vault**  | `hashchain.py`    | Local, append-only, **HMAC-signed** notes — tamper-evident + forged-resistant. No network. |\n| 6  | **Vault MOC**         | `vault_index.py`  | Auto-generated Obsidian Map of Content with `[[wikilinks]]` + CWE cross-links. |\n| 7  | **Cross-project learn**| `cross_learn.py` | Aggregates recurring CWEs → `Common-Mistakes.md` + CI guardrail suggestions. |\n| 8  | **LLM review**        | `llm_review.py`   | Logic-flaw review via OpenAI-compatible API; auto-detects Ollama/llama.cpp (offline) or OpenAI. No key → safe skip. |\n| 9  | **Living arch table** | `sample_repo.py`  | Detects stacks in mined repos; flags missing rows in the decision table. |\n| 10 | **Auto-git**          | `proj_gen`/`audit`| Tags `scaffold-\u003cdate\u003e` / `audit-clean-\u003cdate\u003e` — every green state is versioned. |\n| 12 | **Config file**       | `config.py`       | Optional `mincode.toml` for vault path, audit skip-dirs/threshold, LLM model/base_url. |\n\n---\n\n## 📂 Layout\n\n```\nmincode-vuln-arch/\n├── SKILL.md                 # AgentSkills-compatible skill: full workflow + decision table\n├── AGENT.md                 # drop-in cheat-sheet for any AI agent\n├── README.md  LICENSE\n├── pyproject.toml          # pip-installable (mincode_vuln_arch + `mincode` console script)\n├── build_pyz.py            # -\u003e mincode.pyz single-file distribution\n├── mincode.py              # single CLI dispatcher (delegates to scripts/cli.py)\n├── mincode.toml.example    # config template\n├── references/             # deep-dive docs (agentskills-spec, audit, tests, windows, gotchas)\n├── scripts/                # all toolkit scripts (zero-dep)\n│   ├── proj_gen.py          gen_tests.py        audit.py\n│   ├── sample_repo.py       hashchain.py        vault_index.py\n│   ├── cross_learn.py       llm_review.py       gen_ci.py\n│   └── mcp_server.py        cli.py              config.py\n└── vault/                   # Obsidian vault (hash-chained notes; created at runtime)\n```\n\n---\n\n## 🚀 Quick start\n\nPick **one** install mode — they all wrap the same scripts.\n\n\u003cdetails open\u003e\u003csummary\u003e\u003cb\u003e① Clone (full / dev)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/Falcoraxyz/mincode-vuln-arch\nexport OBSIDIAN_VAULT_PATH=\"$PWD/vault\"   # optional, for vault output\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e② Pip-installable (global \u003ccode\u003emincode\u003c/code\u003e command)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npip install .            # or: uv pip install .   /   uvx --from . mincode\nmincode audit \u003cproject\u003e --no-vault\nmincode --help\n```\nNo third-party dependencies. Installs as the `mincode_vuln_arch` package.\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e③ Single file (zero-install, any Python 3.8+)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npython build_pyz.py                 # -\u003e mincode.pyz (one self-contained file)\npython mincode.pyz audit \u003cproject\u003e --no-vault\n```\nShare `mincode.pyz` directly — no pip, no clone. Runs on any Python 3.8+ host.\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e④ MCP server (native tool for Claude Desktop / Cursor / Zed / Cline)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npython scripts/mcp_server.py        # or: mincode mcp\n```\nClient config (`claude_desktop_config.json` / `mcp.json`):\n```json\n{ \"mcpServers\": { \"mincode\": {\n    \"command\": \"python\",\n    \"args\": [\"/path/to/mincode-vuln-arch/scripts/mcp_server.py\"] } } }\n```\nSpeaks MCP JSON-RPC (2024-11-05) over stdio, **zero dependencies**.\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003e⑤ As a Hermes / AgentSkills skill\u003c/b\u003e\u003c/summary\u003e\n\nDrop (or symlink) the repo into your skills root — `SKILL.md` frontmatter is\nAgentSkills-compatible, so any AgentSkills-aware loader picks it up directly:\n```bash\nln -s \"$PWD\" ~/.hermes/skills/software-development/mincode-vuln-arch   # Hermes\nln -s \"$PWD\" ~/.claude/skills/mincode-vuln-arch                        # Claude Code\n```\n\u003c/details\u003e\n\n### Enable the audit gate in one command\n```bash\nmincode init .          # writes mincode.toml + .github/workflows/audit.yml\n```\nThis scaffolds a CI workflow that runs `mincode audit . --sarif audit.sarif`\nand **fails on HIGH findings**.\n\n---\n\n## 🔧 Usage\n\n```bash\nmincode gen \u003cp\u003e      # scaffold minimal project (auto git + tag)\nmincode tests \u003cp\u003e    # generate typed smoke tests\nmincode audit \u003cp\u003e    # vuln audit + graded CI gate (HIGH blocks \"done\")\nmincode mine \u003crepo\u003e  # mine clean architecture patterns\nmincode llm \u003cp\u003e      # LLM logic-flaw review (skips if no backend)\nmincode vault \u003ccmd\u003e  # append / verify / diff / status\nmincode moc          # rebuild Obsidian MOC\nmincode learn        # aggregate recurring CWE\nmincode ci \u003crepo\u003e    # generate CI gate workflow\nmincode init \u003crepo\u003e  # one-shot: mincode.toml + CI into a repo\nmincode mcp          # start MCP server (stdio)\n```\nAll extra args pass through (`--vault`, `--no-vault`, `--sarif`, `--threshold`, …).\nVault defaults to `./mincode-vault` when `OBSIDIAN_VAULT_PATH` / `--vault` / `mincode.toml` are unset.\n\n**Direct scripts (also fine):** `python scripts/audit.py myapp`, `python scripts/gen_tests.py myapp`, …\n\n### Example audit output\n```\nAUDIT demo — 1 HIGH, 2 MED, 1 LOW\n  HIGH  CWE-78  shell=True in src/cli.py:42        (eval/exec)\n  MED   CWE-89  SQL string concat in src/db.py:17  (SQLi)\n  MED   CWE-502 unsafe yaml.load in src/cfg.py:9    (deserialization)\n  LOW   CWE-798 hardcoded API key in src/secret.py:3\nGRADE: D  (penalty 36)   CWEs: {CWE-78, CWE-89, CWE-502, CWE-798}\n```\n\n---\n\n## 🧠 How it works\n\n```text\n   code ──► proj_gen ──► gen_tests ──► audit ──► (llm_review)\n                                    │\n            sample_repo ◄── clean repos (human or AI)\n                                    │\n                          ┌─────────┴──────────┐\n                     hashchain.py          vault_index.py\n                  (HMAC-signed ledger)    (Obsidian MOC)\n                          │                    │\n                     cross_learn.py ◄──────────┘\n                  (Common-Mistakes.md, guardrails)\n                          │\n                   persistent memory (permanent)\n```\n\n```mermaid\nflowchart LR\n    A[code] --\u003e B[proj_gen]\n    B --\u003e C[gen_tests]\n    C --\u003e D{audit}\n    D --\u003e|HIGH| E[block done]\n    D --\u003e|clean| F[audit-clean tag]\n    D --\u003e G[llm_review]\n    H[clean repos] --\u003e I[sample_repo]\n    I --\u003e D\n    I --\u003e J[hashchain]\n    J --\u003e K[vault_index / MOC]\n    J --\u003e L[cross_learn]\n```\n\nThe vault is a **local hash-chain** — each note links to the previous note's\nhash and is **HMAC-signed** with a per-vault key. Editing a note *or* the ledger\ntogether is caught on `verify`. This is tamper-evident + forged-resistant, **not**\na distributed ledger — no network required.\n\n---\n\n## 🏗️ Architecture decision table\n\nThe skill picks the **optimal + stable + newest usable** stack per concern.\nFull table lives in [`SKILL.md`](SKILL.md); `sample_repo.py` checks mined repos\nagainst it and suggests new rows.\n\n| Stack | Pick |\n|-------|------|\n| CLI | stdlib + argparse |\n| Web API | FastAPI (or stdlib `http.server` if tiny) |\n| Data / ETL | Python modules + pydantic |\n| Frontend | Vite + vanilla TS / Svelte |\n| Long-running svc | supervisor, config via env |\n| Storage | SQLite (Postgres only if scale demands) |\n\n---\n\n## 🤖 Agent-agnostic\n\nThis toolkit is designed to be called by **any** agent, not just Hermes:\n\n| Integration | How | Best for |\n|-------------|-----|----------|\n| **AgentSkills** | `SKILL.md` in a skills dir | agents with a skill system |\n| **MCP** | `python scripts/mcp_server.py` | Claude Desktop / Cursor / Zed / Cline native tools |\n| **CLI** | `python mincode.py \u003ccmd\u003e` | shell-based agents / humans |\n| **pip/uvx** | `pip install .` → `mincode` | global install, any agent |\n| **pyz** | `python mincode.pyz \u003ccmd\u003e` | single-file, zero-install, air-gapped |\n\nNo hardcoded paths. Zero third-party dependencies. See [`AGENT.md`](AGENT.md)\nfor a copy-paste cheat-sheet and [`references/agentskills-spec.md`](references/agentskills-spec.md)\nfor the compatibility contract.\n\n---\n\n## 📌 Notes \u0026 limits\n\n- Audit is **heuristic** — a clean scan is not a guarantee. `llm_review.py`\n  covers logic blind spots when a model endpoint is available.\n- `pip-audit` (dep CVEs) and `bandit` are optional install/network extras.\n- The hash-chain is **local** tamper-evidence, not a blockchain. Never commit\n  the HMAC key (`vault/._chain/.key` is gitignored).\n- Run generated tests with `python tests/\u003cmod\u003e_test.py` (reliable on Windows;\n  `unittest discover` can report 0 in some envs).\n\n---\n\n## 🗺️ Roadmap\n\nAll original ideas + the portability track have shipped. Status snapshot in\n[`ROADMAP.md`](ROADMAP.md).\n\n---\n\n## 📄 License\n\n[Apache-2.0](LICENSE) © Falcoraxyz\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalcoraxyz%2Fmincode-vuln-arch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffalcoraxyz%2Fmincode-vuln-arch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalcoraxyz%2Fmincode-vuln-arch/lists"}