Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (50 loc) · 2.68 KB

CLAUDE.md

File metadata and controls

73 lines (50 loc) · 2.68 KB
Raw

npm-scanner

@.claude/marr/MARR-PROJECT-CLAUDE.md

Purpose

Security toolkit protecting Node.js developers from npm supply chain attacks (PhantomRaven and similar). Provides auditing, validation, and monitoring tools for detecting malicious packages before they compromise systems.

Architecture

Entry Point

  • npm-scanner.sh - Main CLI with scan and validate commands

Scripts (in scripts/)

Core:

  • audit-installed-packages.sh - Unified scanning tool for projects and packages
  • npm-security-audit.sh - Single project scanner (used internally)
  • npm-audit-lib.sh - Shared library with common functions

Pre-Installation:

  • package-validator.sh - Pre-installation risk assessment with typosquatting detection

Response & Automation:

  • credential-rotation-script.sh - Post-compromise incident response guide
  • scheduled-audit-script.sh - Automated scheduling with alerting
  • generate-summary-report.sh - Report aggregation
  • npmrc-security-config.sh - Secure configuration template

Constraints

Documentation Sync

  • ALWAYS update the corresponding docs/ file when modifying any script
  • NEVER commit script changes without corresponding documentation updates
  • WHEN adding new features that affect architecture, update docs/contributors/reference/architecture.md
  • WHEN adding new command-line options, update the script's documentation file

Code Quality

  • ALWAYS use absolute paths for script references to ensure scripts work from any directory
  • NEVER use pipe-to-while patterns that create subshells and lose variable state
  • WHEN caching npm data, use the shared library functions in npm-audit-lib.sh
  • ALWAYS convert relative OUTPUT_DIR paths to absolute before changing directories

Security

  • NEVER commit credentials or API keys
  • ALWAYS validate user input at system boundaries
  • WHEN detecting suspicious packages, err on the side of flagging them

Zero Dependencies Policy

  • NEVER add package.json, package-lock.json, or node_modules to this project
  • This toolkit audits npm packages - depending on them creates supply chain risk
  • Use only: bash scripts and system tools (jq, curl, etc.)
  • CI will fail if npm dependency files are detected

File Structure

  • npm-scanner.sh - Main entry point
  • scripts/ - All implementation scripts
  • docs/ - Script documentation and reference materials
  • templates/ - Report templates (common, packages, projects)
  • reports/ - Output directory for scan results

References

  • Documentation: docs/README.md
  • Contributing: docs/contributors/how-to/contributing.md
  • CI/CD integration: docs/users/how-to/integrate-with-ci.md