Feature/artifact blocklist publish audit

.shieldcommit.yaml

@@ -0,0 +1,53 @@
+# ShieldCommit Configuration File
+# Save this as .shieldcommit.yaml in the root of your repository
+
+# --- Secrets Detection Configuration ---
+secrets:
+  enabled: true
+  entropy_threshold: 4.0
+  custom_patterns:
+    - "AKID[A-Z0-9]{16}"  # AWS Access Key IDs
+    - "AKIA[0-9A-Z]{16}"
+
+# --- Artifact Pattern Blocklist Configuration ---
+artifacts:
+  enabled: true
+
+  # Add patterns to the default blocklist
+  block_patterns:
+    - "*.tfstate"                # Terraform state — contains secrets and resource IDs
+    - "*.tfstate.backup"
+    - "kubeconfig"
+    - "*.kubeconfig"
+    - ".kube/config"
+    - "secrets.yaml"             # Kubernetes secrets
+    - "values-prod.yaml"         # Helm values with secrets
+
+  # Remove patterns from the default blocklist
+  # Useful when your team intentionally commits certain files
+  allow_patterns:
+    # Example: if your team intentionally commits dist/ to the repo
+    # - "dist/*"
+
+  # Override severity for specific patterns
+  # 'error' = block the commit
+  # 'warning' = warn but allow commit to proceed
+  severity:
+    "*.map": error               # Sourcemaps — critical security risk
+    "*.pyc": warning             # Python bytecode — not critical
+    ".DS_Store": warning         # macOS metadata — noise
+    "*.pem": error               # Private keys — critical
+    "*.key": error               # Private keys — critical
+    ".env.production": error     # Production secrets — critical
+
+# --- Publish Audit Configuration ---
+# Used by: shieldcommit audit-publish
+publish_audit:
+  enabled: true
+  package_type: auto            # auto | npm | pypi
+  fail_on_warnings: false        # Set to true for strict CI mode
+  size_limit_mb: 10              # Warn if package exceeds this size
+  custom_ignore_suggestions:     # Additional patterns to suggest for .npmignore/MANIFEST.in
+    - "**/*.test.ts"
+    - "**/*.spec.js"
+    - "test/*"

FEATURES.md

@@ -0,0 +1,325 @@
+# ShieldCommit - New Features Implementation
+
+## Overview
+Two major features have been added to ShieldCommit to enhance its security scanning capabilities:
+
+1. **Feature 1: Artifact Pattern Blocklist** - Prevents dangerous files from being committed
+2. **Feature 2: Publish Audit** - Pre-flight checks before publishing packages to npm/PyPI
+
+## Feature 1: Artifact Pattern Blocklist
+
+### What It Does
+Before a commit is allowed, ShieldCommit scans all staged files against a blocklist of dangerous file patterns that should never enter version control. If a match is found, the commit is blocked with a clear human-readable message and fix suggestions.
+
+### Default Patterns (Fallback)
+```python
+*.map                    # Sourcemaps — key security risk
+*.js.map, *.ts.map, *.css.map
+dist/*, build/*, .next/*, out/*  # Compiled output directories
+__pycache__/*, *.pyc    # Python cache
+*.pem, *.key            # Private keys & certificates
+*.p12, *.pfx, *.crt
+.env.production         # Environment files with secrets
+.env.staging, .env.local
+.idea/*, *.suo, *.user  # IDE metadata
+.DS_Store               # macOS noise
+```
+
+### Configuration via `.shieldcommit.yaml`
+
+The config file (saved in repo root) allows teams to:
+- **Extend** the blocklist with custom patterns
+- **Allow** patterns to override the defaults
+- **Set severity** levels (error/warning)
+
+Example:
+```yaml
+artifacts:
+  enabled: true
+
+  block_patterns:
+    - "*.tfstate"           # Add Terraform state
+    - "kubeconfig"
+    - "secrets.yaml"
+
+  allow_patterns:
+    - "dist/*"              # Our team commits dist/
+
+  severity:
+    "*.map": error          # Block sourcemaps
+    ".DS_Store": warning    # Warn on macOS files
+```
+
+### Severity Levels
+- **error** — Block the commit, exit with code 2
+- **warning** — Print warning, allow commit to proceed
+
+### Usage in Scan Command
+
+The `scan` command now includes artifact detection:
+
+```bash
+shieldcommit scan              # Scans staged files for both secrets AND artifacts
+shieldcommit scan file.py      # Scans specific file
+
+# Output when violations found:
+🛡  ShieldCommit — Artifact Detected
+
+  File   : dist/main.js.map
+  Pattern: *.map
+  Risk   : Sourcemap files embed your entire original source code as
+           plain text inside a JSON blob. This is exactly how Anthropic
+           accidentally leaked 513,000 lines of Claude Code on March 31 2026.
+
+  Fix    : Add "*.map" to your .gitignore
+           $ echo "*.map" >> .gitignore
+
+  To override (not recommended):
+           $ git commit --no-verify
+```
+
+### Exit Codes for Scan Command
+- **0** — No secrets or critical artifacts found
+- **1** — Secrets detected (blocking)
+- **2** — Artifact violations detected (blocking)
+
+---
+
+## Feature 2: Publish Audit
+
+### What It Does
+A standalone CLI command (`audit-publish`) that runs **before** you publish a package to npm or PyPI. It simulates what the publish command would include, scans those files for artifact and secret violations, and produces a risk report.
+
+**Important**: It only audits — it does NOT actually publish.
+
+### CLI Interface
+
+```bash
+# Auto-detect package type (npm or pypi)
+shieldcommit audit-publish
+
+# Explicit package type
+shieldcommit audit-publish --type npm
+shieldcommit audit-publish --type pypi
+
+# Output formats
+shieldcommit audit-publish --output json
+shieldcommit audit-publish --output table      # default
+
+# Write fix suggestions to file
+shieldcommit audit-publish --fix-suggestions   # Creates .npmignore.suggested
+
+# CI mode — fail on warnings too
+shieldcommit audit-publish --ci
+```
+
+### How It Works
+
+**For npm packages:**
+- Runs: `npm pack --dry-run --json`
+- Parses output to get files npm would include
+- Automatically respects `.npmignore` and `package.json` "files" field
+
+**For PyPI packages:**
+- Analyzes `pyproject.toml` or `setup.py`
+- Checks what's NOT in `.gitignore` and would be included
+- Can also use `python -m build --dry-run`
+
+### Scanning Logic
+For each file to be published:
+1. Check against **artifact pattern blocklist** (same as scan command)
+2. Check for **secrets** using intelligent detection
+3. Check **package size** against configured limits
+
+### Output — Table Format (Default)
+
+```
+🛡  ShieldCommit — Publish Audit
+    Package : @yourorg/shieldcommit
+    Version : 1.2.0
+    Type    : npm
+    Files   : 47 files will be published (12.3 MB total)
+
+  VIOLATIONS
+  ──────────────────────────────────────────────────────────
+  SEVERITY  FILE                        ISSUE
+  ──────────────────────────────────────────────────────────
+  ERROR     dist/main.js.map (58.9 MB)  Sourcemap — embeds full source
+  ERROR     .env.production             Env file — may contain secrets
+  WARNING   .DS_Store                   OS metadata noise
+  ──────────────────────────────────────────────────────────
+  2 errors, 1 warning
+
+  SUGGESTED FIXES
+  ──────────────────────────────────────────────────────────
+  Add to .npmignore:
+    *.map
+    .env.*
+    .DS_Store
+
+  Or restrict package.json "files" to only what you intend:
+    "files": ["dist/**/*.js", "src/", "README.md"]
+  ──────────────────────────────────────────────────────────
+
+  ❌  Publish audit FAILED — fix errors before publishing.
+      Run with --fix-suggestions to write .npmignore.suggested
+```
+
+### Output — JSON Format (For CI Pipelines)
+
+```json
+{
+  "package": "@yourorg/shieldcommit",
+  "version": "1.2.0",
+  "type": "npm",
+  "total_files": 47,
+  "total_size_mb": 12.3,
+  "violations": [
+    {
+      "severity": "error",
+      "file": "dist/main.js.map",
+      "size_mb": 58.9,
+      "pattern": "*.map",
+      "issue": "Sourcemap file embeds full original source code"
+    }
+  ],
+  "passed": false,
+  "error_count": 2,
+  "warning_count": 1
+}
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Clean, safe to publish |
+| 1 | Warnings only (or warnings in non-CI mode) |
+| 2 | Errors found, do not publish |
+
+### Configuration via `.shieldcommit.yaml`
+
+```yaml
+publish_audit:
+  enabled: true
+  package_type: auto          # auto | npm | pypi
+  fail_on_warnings: false     # Set true for strict CI mode
+  size_limit_mb: 10           # Warn if package exceeds this
+  custom_ignore_suggestions:  # Appended to output
+    - "*.test.ts"
+    - "test/*"
+```
+
+---
+
+## File Structure
+
+### New Files Created
+
+```
+src/shieldcommit/
+├── config.py              # Configuration parser for .shieldcommit.yaml
+├── artifact_detector.py   # Artifact pattern matching and blocking
+├── publish_audit.py       # Publish audit implementation
+└── __main__.py            # (Updated) New CLI commands
+
+.shieldcommit.yaml         # Example configuration file
+
+tests/
+├── test_artifact_detector.py   # Tests for artifact scanning
+└── test_config.py              # Tests for configuration
+```
+
+### Modified Files
+
+```
+src/shieldcommit/
+├── scanner.py         # Updated to include artifact detection
+├── __main__.py        # Added audit-publish command, updated scan output
+
+requirements.txt      # Added: pyyaml, toml
+```
+
+---
+
+## Integration Points
+
+### Pre-Commit Hook
+The artifact scanning is automatically integrated into the existing pre-commit hook. When `shieldcommit scan` is called (either directly or via the hook), it now:
+1. Scans for secrets
+2. **NEW**: Scans for artifact violations
+3. Scans for version warnings
+4. **NEW**: Blocks commits with error-level artifacts
+
+### CI/CD Pipeline
+The new `audit-publish` command is designed for CI integration:
+
+```yaml
+# Example: GitHub Actions
+- name: Audit before publish
+  run: shieldcommit audit-publish --ci --output json
+
+- name: Publish to npm
+  if: success()
+  run: npm publish
+```
+
+---
+
+## Implementation Details
+
+### Pattern Matching
+- Uses Python's `fnmatch` module for glob-style pattern matching
+- Supports wildcards (`*`), directory patterns (`dir/*`), and exact matches
+- Case-insensitive on most filesystems
+
+### Configuration Loading
+- Looks for `.shieldcommit.yaml` in the repository root
+- Falls back to hardcoded defaults if file not found
+- Gracefully handles missing or malformed YAML
+
+### Severity Handling
+- Each pattern has a severity level (error or warning)
+- Can be overridden per-pattern in `.shieldcommit.yaml`
+- Error violations block operations; warnings only notify
+
+---
+
+## Testing
+
+Tests are provided for:
+- Pattern matching logic
+- Violation creation and formatting
+- Configuration loading and defaults
+- Severity assignment
+- Violation filtering
+
+Run tests:
+```bash
+pytest tests/test_artifact_detector.py
+pytest tests/test_config.py
+```
+
+---
+
+## Future Enhancements
+
+Potential improvements:
+1. Custom pattern syntax support (regex, more complex glob patterns)
+2. Integration with pre-push hook in addition to pre-commit
+3. Plugin system for custom validators
+4. Slack/email notifications on violations
+5. Web UI for configuration management
+6. Statistics and reporting dashboard
+
+---
+
+## References
+
+### Claude Code Incident
+The sourcemap security risk is based on the real Anthropic Claude Code incident (March 31, 2026) where 513,000 lines of code were leaked via committed sourcemaps.
+
+### Related Features
+- Secret detection: Intelligent entropy-based scanning (no patterns)
+- Version warnings: EKS, RDS, AKS, GCP, Azure DB version checks
+- Package manager support: npm, PyPI (setuptools, poetry)