Security Command

`stamp security scan` Command

Find secrets (API keys, passwords, tokens) and other sensitive data in your project before they get committed. Runs 100% locally — nothing is uploaded or sent anywhere.

Syntax

stamp security scan [path] [options]

[path] (optional) – Directory to scan. Defaults to the current working directory. Paths can be relative (./src) or absolute.

Overview

The security scan helps prevent accidentally exposing sensitive credentials by:

Scanning TypeScript, JavaScript, and JSON files for common secret patterns

Generating detailed reports of detected secrets

Integrating with the stamp init command for automated security checks

Options

Option	Short	Description
`--out <file>`	`-o`	Output file path for the security report (default: `stamp_security_report.json`)
`--quiet`	`-q`	Output only JSON statistics, suppress other messages
`--help`	`-h`	Show help information

What It Does

The stamp security scan command:

Scans TypeScript, JavaScript, and JSON files for common secret patterns

Detects API keys, passwords, tokens, AWS keys, GitHub tokens, private keys, database URLs, JWT secrets, and more

Generates a detailed JSON security report

Includes file paths, line numbers, secret types, code snippets, and severity levels

Automatically protects the security report file

Adds the report file to .gitignore to prevent accidental commits of sensitive findings

Detected Secret Types

High Severity

API Keys: Patterns like apiKey, api_key, apikey with values ≥20 characters
AWS Access Keys: AWS access key IDs (format: starts with specific prefix followed by 16 alphanumeric characters)
GitHub Tokens: GitHub personal access tokens and fine-grained tokens
Private Keys: RSA or other private key blocks (BEGIN PRIVATE KEY)
Passwords: Patterns like password, passwd, pwd with values ≥8 characters
Tokens: Authentication tokens and bearer tokens ≥20 characters
OAuth Secrets: OAuth client secrets and similar patterns ≥16 characters
Database URLs: Connection strings with embedded credentials (PostgreSQL, MySQL, MongoDB)
JWT Secrets: JWT signing keys and secrets ≥16 characters

Medium Severity

Generic Secrets: Patterns like secret, secret_key with values ≥16 characters

Security Report Format

The security scan generates a JSON report with the following structure:

{
  "type": "LogicStampSecurityReport",
  "schemaVersion": "0.1",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "projectRoot": "/path/to/project",
  "filesScanned": 42,
  "secretsFound": 3,
  "matches": [
    {
      "file": "src/config.ts",
      "line": 15,
      "column": 12,
      "type": "API Key",
      "snippet": "const apiKey = 'FAKE_SECRET_KEY'",
      "severity": "high"
    }
  ],
  "filesWithSecrets": [
    "src/config.ts",
    "src/secrets.js"
  ]
}

Report Fields:

type: "LogicStampSecurityReport" (report format identifier)
schemaVersion: "0.1" (schema version)
createdAt: ISO 8601 timestamp
projectRoot: Absolute path to project root
filesScanned: Total files scanned
secretsFound: Total secret matches detected
matches: Array of individual secret matches
filesWithSecrets: Array of file paths containing secrets (sorted)

Each match shows the file path, line and column numbers, secret type, a code snippet (about 40 characters), and severity level (high, medium, or low).

🔒 Automatic `.gitignore` Protection

SECURITY CRITICAL: Security reports contain sensitive information (locations of detected secrets, line numbers, code snippets), so stamp security scan automatically ensures the report file is added to .gitignore to prevent accidental commits. This happens automatically and cannot be disabled — the security report must never be committed to version control.

The security report contains:

File paths where secrets were detected
Line and column numbers pointing to secret locations
Code snippets showing the context around secrets
Severity levels and secret types

Even if no secrets are found, the report structure itself reveals which files were scanned, which could be sensitive information in some contexts.

Secret Sanitization in Context Files

When generating context JSON files, any secrets detected in the security report are automatically replaced with "PRIVATE_DATA" in the generated files.

Source files are never modified - your actual code remains unchanged

Sanitization happens automatically when a security report exists

Works with all code inclusion modes (--include-code header and --include-code full)

Code inclusion modes and credentials:

none mode: No code is included, so credentials cannot appear in bundles
header mode: Only JSDoc @uif metadata blocks are included (not implementation code), so credentials will not appear in bundles
header+style mode: Same as header mode (only metadata), plus style information, so credentials will not appear in bundles
full mode: Full source code is included, so credentials could appear unless sanitized. Sanitization automatically replaces detected secrets with "PRIVATE_DATA" when a security report exists

Even if credentials exist in your source files (which they shouldn't), they can only be included in generated bundles when using --include-code full mode. The other modes only include metadata and contracts, not actual implementation code where credentials would typically be found.

When sanitization happens:

stamp context - Secrets are sanitized in generated context files
stamp context style - Secrets are sanitized in generated context files (same behavior)
If no security report exists, code is included as-is (no sanitization)

This ensures that sensitive credentials never appear in your context JSON files, even if they exist in your source code.

Examples

# Scan the current directory for secrets
stamp security scan

# Scan specific directory
stamp security scan ./src

Exit Codes

No secrets found

Secrets detected

Use in CI/CD pipelines to fail builds when secrets are detected.

Integration with `stamp init`

The security scan runs automatically during project initialization by default:

# Security scan runs automatically
stamp init

# Initialize without prompts (CI-friendly, security scan still runs)
stamp init --yes

# Skip security scan if needed
stamp init --no-secure

By default, stamp init automatically runs a security scan after initialization. This:

Sets up .gitignore patterns

Generates LLM_CONTEXT.md (if prompted and accepted)

Runs stamp security scan to scan for secrets (API keys, passwords, tokens)

Review the security report and use stamp ignore <file> to exclude files with secrets from context generation.

File Types Scanned

The security scan examines the following file types:

TypeScript

.ts, .tsx

JavaScript

.js, .jsx

JSON

.json

Note: Files larger than 10MB are automatically skipped to prevent performance issues. You'll see a warning message if any files are skipped due to size.

Limitations

Pattern-based detection (may have false positives or miss some formats)
Only scans TypeScript, JavaScript, and JSON files
Files larger than 10MB are skipped (you'll see a warning)
Doesn't detect encrypted secrets or secrets in environment-specific files
Static analysis only (can't detect secrets passed at runtime)

`stamp security scan` Command

Syntax

Overview

Options

What It Does

Detected Secret Types

High Severity

Medium Severity

Security Report Format

🔒 Automatic `.gitignore` Protection

Secret Sanitization in Context Files

Examples

Exit Codes

No secrets found

Secrets detected

Integration with `stamp init`

File Types Scanned

TypeScript

JavaScript

JSON

Limitations

See Also

`init` command

`context` command

Product

Contact

Legal

stamp security scan Command

Syntax

Overview

Options

What It Does

Detected Secret Types

High Severity

Medium Severity

Security Report Format

🔒 Automatic .gitignore Protection

Secret Sanitization in Context Files

Examples

Exit Codes

No secrets found

Secrets detected

Integration with stamp init

File Types Scanned

TypeScript

JavaScript

JSON

Limitations

See Also

`init` command

`context` command

`stamp security scan` Command

🔒 Automatic `.gitignore` Protection

Integration with `stamp init`