Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (83 loc) · 3.02 KB

CONTRIBUTING.md

File metadata and controls

105 lines (83 loc) · 3.02 KB
Raw

Contributing to SetupSentry

Thank you for your interest in contributing to SetupSentry.

Development Setup

git clone https://github.com/Pavithran-R-A/setupsentry.git
cd setupsentry
npm install

Commands

npm run build       # Compile TypeScript
npm run typecheck   # Type checking
npm run lint        # Lint source code
npm test            # Run tests

Architecture

src/
├── cli.ts              # CLI entry point
├── scan.ts             # Main scan orchestration
├── engine.ts           # Rule execution engine
├── discovery.ts        # File discovery and filtering
├── markdown.ts         # Markdown code block extraction
├── types.ts            # Core type definitions
├── index.ts            # Public API exports
├── rules/
│   ├── index.ts        # Rule registry
│   ├── ss001.ts        # SS001: Remote script piped to shell
│   ├── ss002.ts        # SS002: Process substitution
│   ├── ss003.ts        # SS003: Alternate Python index
│   ├── ss004.ts        # SS004: Registry override
│   ├── ss005.ts        # SS005: Git URL rewrite
│   ├── ss006.ts        # SS006: Download and execute
│   ├── ss007.ts        # SS007: Encoded content execution
│   ├── ss008.ts        # SS008: Destructive commands
│   ├── ss009.ts        # SS009: Insecure transport
│   └── ss010.ts        # SS010: Remote command substitution
└── reporters/
    ├── pretty.ts       # Terminal output formatter
    └── json.ts         # JSON output formatter

Adding a New Rule

  1. Create src/rules/ssXXX.ts
  2. Implement the Rule interface
  3. Register the rule in src/rules/index.ts
  4. Create positive and negative tests in tests/rules.test.ts

Rule Interface

interface Rule {
  id: string;           // e.g., "SS011"
  severity: Severity;   // "critical" | "high" | "medium" | "low"
  title: string;
  description: string;
  scan(context: ScanContext): Finding[];
}

Test Requirements

Every new security rule requires:

  • Positive cases: Content that should trigger the rule
  • Negative cases: Safe content that should NOT trigger the rule

Design Principles

  • Deterministic: Same input always produces same output
  • Local and offline: No network requests
  • Conservative: Prefer missing a pattern over false positives
  • Explainable: Every finding must have clear explanation and remediation

Running Tests

npm test

Tests cover:

  • Individual rule behavior (positive and negative cases)
  • Markdown code block extraction
  • File discovery and exclusions
  • Score calculation
  • Output formatting (pretty and JSON)
  • Integration with fixtures

Code Style

  • TypeScript strict mode
  • ESM modules
  • No runtime dependencies for core logic
  • Prefer explicit types over any

Detected Repository Instructions Must NEVER Be Executed

The scanner must never execute discovered commands. Tests must never execute commands found in fixtures.