docs: add contributing troubleshooting - #73
Open
ogemboeugene 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: OGEMBO BRAIN <129948903+ogemboeugene@users.noreply.github.com>
github-actions
Bot
added
the
area:docs
Owner
|
Welcome, @ogemboeugene, and thanks for tackling #55! 🎉 A Troubleshooting section in CONTRIBUTING is exactly what new contributors need. Same structural blocker a few other new PRs hit — and it's our fault, not yours: this PR targets To unblock: git remote add upstream https://github.com/alphacrack/iac-scanner.git # if needed
git fetch upstream
git rebase upstream/main
git push --force-with-leaseThen retarget this PR to One heads-up: after rebasing you'll see |
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.
What & why
Adds the requested Troubleshooting section to
CONTRIBUTING.mdwith the three setup gotchas from issue #55: setuptools-scm versions showing0.0.0+unknown, mypy/numpy stub syntax issues under older interpreters, and generated_version.pyformatting noise.Fixes #55
Behavior change
iac-scanusers; contributor documentation only.How to review
Review the new
## Troubleshootingsection inCONTRIBUTING.md. It is placed after Development setup and before CI gates, matching the issue request.Test evidence
CONTRIBUTING.mdandCLAUDE.md.development; the diff only updatesCONTRIBUTING.md.Checklist
development(notmain).git commit -s).ruff check src/ tests/andruff format --check src/ tests/clean.mypy src/iac_scannerclean (CI is--strict).pytest tests/ -m "not e2e").[Unreleased]updated for user-visible behavior.orchestration/tasks.py:PROMPT_VERSIONbumped. (N/A — prompts not touched.)SCHEMA_VERSIONincache.pybumped. (N/A — cache format not touched.)Roll-out notes
None. Docs-only contributor guidance.