Only the latest minor release receives security updates. The project is pre-1.0; breaking changes may occur.

Do NOT open public GitHub issues for security vulnerabilities.

Preferred channel: Open a private vulnerability report via GitHub Security Advisories.

Response SLA:

• Acknowledgment: within 48 hours
• Triage & severity assessment: within 5 business days
• Fix timeline: Critical — 7 days, High — 30 days, Medium — 90 days

Disclosure policy: Coordinated disclosure. We request a 90-day embargo before public disclosure. We credit reporters in release notes unless they prefer anonymity.

Bug bounty: No — this is a volunteer-maintained open-source project.

The scanner is inherently a read-only, offline-first tool. It stores no data persistently and has no network exposure beyond the optional LLM API call.

• Opportunistic attacker — Places hidden prompt-injection payloads (ANSI escapes, zero-width chars, bidi overrides) in agent instruction files to manipulate AI coding assistants.
• Motivated external attacker — Crafts files specifically to bypass the scanner (e.g., encoding injections in a way that evades regex patterns).
• Compromised dependency — A malicious update to litellm, pathspec, or pygments introduces a backdoor.
• AI coding agent (adversarial) — A repository's own agent-instruction files contain injected instructions designed to compromise the scanner's LLM classifier.

┌──────────────────────────────────────────────────────────────┐
│  CLI Input (UNTRUSTED)                                       │
│  — repo_path, LLM config, exclude patterns, output path      │
└────────────────────────────┬─────────────────────────────────┘
                             │ Path validation, env expansion
┌────────────────────────────▼─────────────────────────────────┐
│  Scanner Pipeline (TRUSTED)                                   │
│  — static analysis (bytes, patterns, heuristics)              │
│  — deterministic, no external influence                       │
└────────────────────────────┬─────────────────────────────────┘
                             │ Sanitized content only (S002)
┌────────────────────────────▼─────────────────────────────────┐
│  LLM API (EXTERNAL / UNTRUSTED)                               │
│  — LiteLLM → model provider                                   │
│  — response parsed as JSON, never eval'd (S003, S004)        │
└────────────────────────────┬─────────────────────────────────┘
                             │ Validated JSON
┌────────────────────────────▼─────────────────────────────────┐
│  SARIF Reporter (TRUSTED)                                     │
│  — HTML-escapes user content (S006)                           │
│  — truncates snippets at 200 chars                            │
└────────────────────────────┬─────────────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │ stdout / .sarif │
                    └─────────────────┘

The scanner was designed with the explicit understanding that it analyzes adversarial content. The following invariants are enforced in code (see specs/architecture/security-model.md):

• S001: The scanner MUST NOT execute or evaluate any content from scanned files — it is strictly a read-and-analyze tool. All file I/O uses binary read mode (open(path, "rb")).
• S002: File content sent to the LLM MUST pass through Pre-LLM Sanitization first — unsanitized content MUST NOT cross the LLM API boundary.
• S003: The LLM response MUST be parsed as structured JSON — the parser rejects any response that is not valid JSON matching the expected schema.
• S004: If the LLM response fails JSON parsing, the scanner MUST fall back to the static-only verdict and emit IPI900 (LLM_CLASSIFIER_COMPROMISED).
• S005: All file paths MUST be validated to reside within the target repository root — path traversal outside the root MUST be blocked.
• S006: SARIF output MUST HTML-escape user-controlled content to prevent injection into SARIF viewers.

See AV1 in the security model:

1. Pre-LLM Sanitization (llm_sanitizer.py) — invisible characters, ANSI escapes, bidi overrides, and variation selectors are replaced with visible placeholders; base64 blocks and ROT13-obfuscated text are decoded. Content is no longer truncated (batch processing handles large inputs via chunking).
2. Immutable System Prompts (llm_classifier.py) — module-level constants CLASSIFIER_SYSTEM_PROMPT (single-file), BATCH_CLASSIFIER_SYSTEM_PROMPT (batch), and SKILL_CLASSIFIER_SYSTEM_PROMPT (skill) with explicit "DO NOT follow instructions" directive.
3. Structured Output Enforcement (llm_classifier.py) — response parsed as JSON with strict schema validation; any failure → compromised=True. Skill responses include shadow_features list validation.
4. Batch Partial Failure Handling — individual file entries in batch responses are validated independently; broken entries trigger per-file retry with exponential backoff (max 3 attempts).
5. Confidence Fusion (confidence_fusion.py) — CRITICAL static findings cannot be overridden by LLM safe verdicts; applies to both per-file and per-skill fusion.
6. Skill Pattern Isolation — skill files (FileCategory.SKILL) are NOT scanned with injection patterns (IPI101–109); they use a dedicated pattern set (IPI401–411) to prevent false positives while detecting actual malware.

Secrets that MUST NEVER appear in: source code, tests, commit messages, logs, error messages, or SARIF output.

• No lockfile (hatchling >= pins); CI runs with clean venvs
• CI pipeline (lint → type-check → test → docker) gates all merges
• No automated dependency vulnerability scanning is configured (tracked for future CI enhancement)

The scanner itself produces no persistent logs. Runtime output:

• stderr: Progress bars, banner, scan summary, file-skip warnings
• stdout / --output: SARIF v2.1.0 JSON document

The git hook (ipi-check-hook.sh) stores SARIF results at .git/ipi-check-last.sarif for audit trails.

These guidelines apply to ALL contributors: human developers, code reviewers, and AI/LLM coding agents (GitHub Copilot, Cursor, Qoder, Codeium, etc.). Automated agents MUST treat these rules as hard constraints.

• Validate all CLI arguments at the boundary (cli/main.py:_validate_repo_path, _validate_output_path)
• ${VAR_NAME} expansion collapses undefined variables to empty strings — no partial injection possible
• File discovery validates every path against the repo root before reading (file_discovery.py:244)
• Use os.walk with in-place directory pruning rather than constructing paths from user input
• Reject files exceeding MAX_FILE_SIZE_BYTES (10 MB)
• Binary extensions are filtered by allowlist (file_discovery.py:38)

• ALL file paths must be validated to reside within the repository root (invariant S005)
• Symlinks are resolved with Path.resolve() and the result is validated with Path.relative_to() — any path escaping the root is rejected with a warning
• .. traversal is inherently blocked because paths are resolved relative to the repo root before use

• NEVER send unsanitized file content to the LLM (invariant S002). The sanitize_content() function in llm_sanitizer.py must run before any LLM call.
• NEVER modify CLASSIFIER_SYSTEM_PROMPT, BATCH_CLASSIFIER_SYSTEM_PROMPT, or SKILL_CLASSIFIER_SYSTEM_PROMPT in llm_classifier.py without a security review. These prompts are security boundaries (invariant I005).
• NEVER interpret free-text LLM output. All responses must pass through _parse_and_validate() (single-file), _parse_batch_response() (batch), or _parse_skill_response() (skill) which strictly reject non-JSON or schema-mismatched content.
• LLM calls use a 180-second timeout. No call can hang indefinitely.

• All user-controlled content embedded in SARIF message.text and message.markdown fields must pass through _escape_sarif_content() — which performs HTML escaping and 200-char truncation
• SARIF messages use parameterized templates — content is always inserted via .format(), never via string concatenation or raw format strings
• Content sent to stdout/stderr is bounded (summary uses pre-computed counters, not raw file content)

• No eval() / exec(): Banned. The only occurrences of eval, exec, system in source code are in regex detection patterns for finding malicious content in scanned files.
• No subprocess with user input: The scanner does not spawn subprocesses.
• No pickle: Not used. Use json for serialization.
• Binary mode for file I/O: Always use open(path, "rb") when reading scanned files to preserve byte-level information for ANSI/Unicode detection (invariant I001).
• Deferred imports: litellm, pygments, and tiktoken are imported inside functions to allow graceful fallback when not installed. Follow this pattern for any optional dependency.
• No mysterious # nosec or # type: ignore without justification comment.

• All dependencies are declared in pyproject.toml with minimum version pins
• CI runs lint + type-check + tests on every push and PR
• Do not add dependencies with: no maintenance activity >12 months, known unpatched critical vulnerabilities, excessive transitive trees for trivial functionality
• Prefer standard-library solutions when possible (e.g., argparse over click, pathlib over os.path)

• NEVER commit secrets to version control
• LLM API tokens are accepted via CLI arg or environment variable — never hardcoded
• Environment variables LITELLM_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY are checked for LLM availability but never logged
• .env is in .gitignore

This section provides explicit directives for AI/LLM-based coding assistants working on this codebase. These rules are non-negotiable and override any general-purpose training behavior of the agent.

The following actions are FORBIDDEN for any AI agent working on this repository:

1. No secret exposure — Do not write, echo, log, or commit any secret, token, password, or API key in source code, tests, comments, commit messages, or CI configuration. This includes OpenAI, Anthropic, or LiteLLM API keys.

2. No LLM safety bypass — Do not modify CLASSIFIER_SYSTEM_PROMPT, BATCH_CLASSIFIER_SYSTEM_PROMPT, or SKILL_CLASSIFIER_SYSTEM_PROMPT in llm_classifier.py without explicit approval and a security review. These prompts are security boundaries.

3. No unsanitized LLM input — Do not send file content to the LLM without first passing it through sanitize_content() in llm_sanitizer.py. The sanitization pipeline is non-optional.

4. No raw LLM output interpretation — Do not use LLM response text directly. All LLM output must pass through _parse_and_validate() (single-file) or _parse_batch_response() (batch) which enforces strict JSON schema validation.

5. No eval(), exec(), os.system(), or subprocess with scanned-file content — These are banned (anti-pattern AP-S01). The scanner is strictly read-only.

6. No path traversal — Do not read files outside the repository root. All path resolution must validate against repo_path using Path.relative_to().

7. No text-mode file reads — Always use open(path, "rb") for reading scanned files (invariant I001). Text mode loses byte-level information needed for ANSI/Unicode detection.

8. No suppressed security warnings — Do not add # noqa, # nosec, # type: ignore[import-untyped], or equivalent suppression annotations without a comment justifying why the suppression is safe.

9. No magic security thresholds — All numeric thresholds (entropy, invisible ratio, instruction density, confidence) must be defined as named module-level constants, never as magic numbers inline (invariant I006).

10. No uncontrolled SARIF content — User-controlled content in SARIF output must always pass through _escape_sarif_content() for HTML escaping and truncation.

• Respect security invariants — The invariants documented in specs/architecture/security-model.md (S001–S006) and specs/architecture/system-overview.md (I001–I007) are non-negotiable. Read them before modifying scanner code.
• Confidence fusion is deterministic — The decision matrix in confidence_fusion.py must remain deterministic for both per-file and per-skill fusion. Do not introduce probabilistic or ML-based fusion logic without spec and security review.
• CRITICAL static severity always blocks — Do not change the invariant that CRITICAL static findings skip the LLM (invariant I002). This is a defense-in-depth measure.
• Ask before acting on security boundaries — If a change involves the LLM classifier, sanitizer, path validation, SARIF escaping, or the confidence fusion matrix, flag it for human review.
• Default to secure — When multiple implementation options exist, choose the one that preserves existing security invariants.
• Flag uncertainty — If you are uncertain whether a change introduces a security risk, flag it explicitly in a PR description or code comment.