docs: add end-to-end MCP setup guide - #70
Open
adity982 wants to merge 9 commits into
Open
Conversation
License swap and packaging: - Replace "Personal Use License" with Apache-2.0 (NOTICE + classifier + README) - Scrub 27-entry keyword stuffing in pyproject → 10 clean keywords - Add optional extras: [local] (Ollama), [github] (GitHub Models), [mcp], [rules] (Checkov) - Pin langchain to >=0.3,<0.4 to guard against 0.4 breaking changes - Version bump 0.3.2 → 0.4.0 Architecture: - Pydantic models (Finding, FindingsList, VerificationResult, ScanReport) - LLMClient protocol with four providers: OpenAI, Anthropic, GitHub Models (keyless), and Ollama (local). Auto-detect chain: IAC_PROVIDER → Ollama → GitHub → OpenAI → Anthropic - Structured LLM output via with_structured_output() replaces regex JSON parsing - XML <user_iac> fencing + secret redaction + 200KB input cap for prompt-injection defense. Default skip-list excludes .tfstate, .tfvars, .env, .pem, and lock/vendor dirs - Content-addressed SHA256 cache with 30-day TTL; tiktoken-based cost preflight with IAC_MAX_SPEND_USD enforcement - Checkov hybrid mode: rule pre-pass + LLM augment with dedup; graceful auto-fallback - MCP server mode (iac-scan-mcp) exposes scan tools to Claude Desktop / Cursor / Continue.dev for fully keyless use Output: - SARIF 2.1.0 emitter with CWE, framework tags, and severity→level mapping - --format json|sarif|both, --fail-on exit-code policy, --rules-engine, --no-cache, --max-spend, --provider CLI flags - AI-generated banner prepended to every fix file CI + security: - Lint (ruff) + mypy --strict (hard-fail) + pytest + smoke + coverage on Python 3.10–3.13 × ubuntu-latest + macos-latest - Separate security workflow: bandit, ruff-S, pip-audit, gitleaks, self-scan, weekly cron - Nightly E2E matrix (openai/anthropic/github/ollama) with per-run budget caps - PyPI publish upgraded to Trusted Publishing (OIDC), CycloneDX SBOM, Sigstore signing - Dependabot config for pip + github-actions with langchain major-version ignore - Pre-commit hooks: ruff, bandit, gitleaks, private-key detection, large-file check Docs: - Expanded SECURITY.md with five-part threat model (prompt injection, secret exposure, hallucinated fixes, supply chain, cost abuse) and hardening checklist - Contributor Covenant 2.1 CODE_OF_CONDUCT.md - CHANGELOG backfilled for 0.3.0–0.3.2 plus full 0.4.0 entry Tests: - 220 tests, 92% line coverage, zero LLM calls required - Mocked LLMClient fixtures in conftest for deterministic integration tests - Unit coverage for filters, cache, cost, providers, hybrid, SARIF, report writer, Checkov adapter, MCP tool bodies, CLI branches, and scanner edge cases Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The secret-redaction regex tests in tests/test_filters.py intentionally embed fake-but-realistic-looking AWS keys, GitHub tokens, OpenAI keys, and JWTs so we can verify the redactor actually matches them. Default gitleaks rules flagged these as findings on PR alphacrack#7. Scope the allowlist narrowly to test files + samples + the canonical AWS example key (AKIAIOSFODNN7EXAMPLE, which appears in AWS's own docs). Keep default rules active everywhere else, including src/iac_scanner/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
README: - Replace "Quickstart (no API key)" with four keyless paths (GitHub Models, Ollama, MCP, OpenAI/Anthropic) plus the existing no-AI parse path - Document every new CLI flag: --provider, --format, --rules-engine, --fail-on, --no-cache, --max-spend - Add env var reference table (OPENAI_API_KEY, ANTHROPIC_API_KEY, GITHUB_TOKEN, OLLAMA_HOST, IAC_MAX_SPEND_USD, IAC_MAX_INPUT_BYTES, IAC_NO_CACHE, etc.) - Project-layout section updated to show llm/, rules/, models.py, cache.py, cost.py, mcp_server.py, scanners/_filters.py, output/sarif.py - Badge URL fixed to alphacrack/iac-scanner (was bishwasjha/); add Apache-2.0 license badge - Cross-links to SECURITY.md (threat model) and CONTRIBUTING.md (release flow) CONTRIBUTING: - License statement switched from "Personal Use" to Apache-2.0 - DCO sign-off documented (git commit -s) - Development setup covers pre-commit install, bandit, gitleaks, pip-audit, mypy --strict, test markers (smoke / integration / e2e) - CI gates section enumerates every PR check - Releases section rewritten for Trusted Publishing + CycloneDX SBOM + Sigstore signing. Adds one-time setup steps on pypi.org and GitHub env - Dependency management section explains LangChain major-version Dependabot ignore (LLMClient protocol isolates the swap path) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…h CI Core: - `src/iac_scanner/rules/engine.py` now discovers third-party rule engines via the `iac_scanner.rule_engines` entry-point group. `engine="auto"` unions Checkov + every installed plugin; unknown engine raises a clear `RuleEngineError` listing installed plugins. - New `available_engines()` helper reports what's actually installed. - PEP 561 `py.typed` marker ships with the core package. New companion package — `packages/iac-scanner-cdk-nag/`: - `pyproject.toml` declaring an `iac_scanner.rule_engines` entry point `cdk-nag → iac_scanner_cdk_nag.adapter:run_cdk_nag`. - Adapter shells out to `cdk synth --quiet --ci`, parses AwsSolutions / HIPAA.Security-* / NIST800-53.R5-* / PCI.DSS.321-* / FedRAMP-* nag annotations from stderr. Maps IAM5 wildcards, S1 no-encryption, KMS2 no-rotation, APIG2 no-validation to CRITICAL; other Errors to HIGH; Warnings to MEDIUM. Framework inferred from rule-id prefix. - 24 unit tests: severity mapping, framework inference, annotation regex with dotted rule IDs, subprocess happy/timeout/crash/no-annotations paths, `cdk_nag_available()` probe. CI: - New `.github/workflows/publish-nag-pypi.yml`: on `nag-v*` tags or manual dispatch, runs extension tests on Python 3.10–3.13, builds sdist+wheel, generates CycloneDX SBOM, publishes via PyPI Trusted Publishing (OIDC, environment `release-nag`), signs everything with Sigstore, and attaches signatures + SBOM to the GitHub Release. Independent tag namespace from core `v*` tags. - `.github/workflows/ci.yml` gains a `test-extensions` job that installs the extension in editable mode alongside core and verifies plugin discovery works end-to-end. Build job now produces both core and nag distributions as artifacts. Docs: - Core CHANGELOG `[Unreleased]` entry for plugin discovery + py.typed. - Extension ships its own `README.md` and `CHANGELOG.md`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Covers: - GitHub Models (free, uses GITHUB_TOKEN — copy-paste GitHub Actions snippet) - Ollama (fully local, with model-size / VRAM guidance table) - MCP server (Claude Desktop / Cursor / Continue.dev config) - OpenAI / Anthropic direct (for production CI with --max-spend guardrail) Also documents --provider=auto ordering and pairing keyless providers with the Checkov rule-engine pre-pass for deterministic CIS/NIST/PCI tags. Links from README; referenced from the upcoming v0.4.0 launch post. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Click's type=Choice was locking the CLI to {checkov, cdk-nag, auto, none}.
A user who installs a future plugin (e.g. iac-scanner-tfsec) would be rejected
by Click before the dispatcher ever ran.
- Switch --rules-engine to type=str with a rejection hint at parse time:
typos print "Unknown --rules-engine 'foo'. Built-ins: checkov. Installed
plugins: [...]. Use 'none', 'auto', or one of those names."
- Catch RuleEngineError from the pipeline and exit 1 with the engine's own
message, separate from the existing Provider/Cost/Input paths.
- New CLI branch test verifies the helpful-error path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/_posts/2026-04-19-iac-scanner-0-4.md — blog post for the release. - Leads with the keyless pitch, not "we have AI" - Four-provider table with cost/network/setup axes - GitHub Actions snippet for the zero-setup case - Explicitly positions as "complements Checkov, not replaces" - Names the v0.5 / v0.6 backlog so users can see what's next .github/RELEASE_NOTES_v0.4.0.md — staging ground for the GitHub Release body. - Highlights, new providers table, new CLI flags - Deprecations + breaking changes (Apache-2.0 license, skip-list defaults) - Security callouts (injection fencing, redaction, input cap, banner) - Supply chain (Trusted Publishing, SBOM, Sigstore) - Hard numbers (253 tests, 92% coverage, 0 mypy/bandit/gitleaks) Neither file is gated by CI; safe to commit before the release is cut. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- .github/CODEOWNERS: auto-request @alphacrack on every PR, with tighter scoping for release-critical paths (pyproject, workflows, license, NOTICE, SECURITY.md) and architecture-sensitive modules (llm/, orchestration/, companion packages). - .github/ISSUE_TEMPLATE/config.yml: route security vulnerabilities to GitHub Security Advisories (private disclosure per SECURITY.md) and open-ended questions to Discussions, keeping the bug-report and feature-request templates for actual issues. Leaves the existing bug_report.md / feature_request.md / PULL_REQUEST_TEMPLATE.md as-is. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Aditya Datta <crazyme07071996@gmail.com>
github-actions
Bot
added
area:mcp
Owner
|
This is a great first contribution, @adity982 — thank you! 🎉 Commit One structural blocker, same as a couple of the other new PRs — and it's our fault, not yours. Base branch + stale starting pointThis PR targets Please retarget this PR to git remote add upstream https://github.com/alphacrack/iac-scanner.git # if needed
git fetch upstream
git rebase upstream/main
git push --force-with-leaseOne thing to check after rebasingYour Once it's rebased and green, I'll review the final diff and merge. Genuinely nice work — the MCP setup guide fills a real gap. 🙌 |
3 tasks
alphacrack
added a commit
that referenced
this pull request
Aug 5, 2026
## Why Three first-time-contributor PRs open right now (#68, #69, #70) were all cut from a stale base and are unmergeable — because `CONTRIBUTING.md`, `CLAUDE.md`, and the PR template told them to branch from and target **`development`**, a branch frozen ~27 commits behind `main` since the v0.4.0 era. Everything actually ships from `main` (now protected). This PR fixes the misdirection. ## Changes - **CONTRIBUTING.md** — branch from / target `main`; add a one-time fork-sync snippet (`git remote add upstream … && git fetch upstream`) and a "if your PR shows dozens of files, rebase" troubleshooting note. - **PULL_REQUEST_TEMPLATE.md** — target `main`; the checklist now asks authors to confirm their branch is rebased on current `main` (diff shows only their files). - **CLAUDE.md** — state that `main` is the single trunk. ## Follow-up (separate, needs maintainer) Delete the `development` branch now that nothing points at it. Its 8 commits are old pre-squash v0.4.0 work already represented in `main`. ## Checklist - [x] Docs-only, no code/runtime change - [x] DCO signed - [x] Makes the review comments left on #68/#69/#70 accurate Fixes the root cause behind #68, #69, #70 base confusion. Signed-off-by: alphacrack <18480504+alphacrack@users.noreply.github.com>
adity982
marked this pull request as ready for review
August 25, 2026 04:53
github-actions
Bot
added
dependencies
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
iac-scan-mcp --helppath so verification does not start a hanging stdio sessionValidation
PYTHONPATH=src python -m pytest tests/test_mcp_server.py -q(11 passed)python -m iac_scanner.mcp_server --helpmatches the documented outputCloses #50