Recodey Shield

Recodey Shield is a CLI-first AI security platform for risk reduction, detection, verification, and developer-friendly code verification. It scans projects before launch, detects common high-risk security issues, produces evidence-backed findings, and generates developer-friendly reports.

Disclaimer: Recodey Shield helps with risk reduction, detection, verification, and launch-readiness support. It does not guarantee 100% security or complete hacking prevention, and it is not a replacement for expert penetration testing. License checks are not legal advice.

Current Status

Status: v0.4.2 — Maintainer Safety and Package Trust Polish (Released)

[!NOTE] v0.4.2 is the current published stable version on npm. Install with npm install -g recodey-shield or run directly with npx [email protected] scan --quick ..

• npm package is published on the registry as [email protected].
• npx [email protected] works out of the box.
• Global npm install -g recodey-shield works.
• recodey-shield doctor verifies environment readiness.
• All scanning is local-first & offline by default — source code never leaves your machine.

v0.2.1 — Adoption Documentation, CI Templates, and Configuration Docs

This release improved developer onboarding, workflow integration, and configuration visibility:

• CI Templates: Added templates and copy-paste recipes for GitHub Actions and GitLab CI workflows.
• Troubleshooting Guides: Added npm/npx caching and resolution tips for seamless CLI execution.
• PR Summaries Guidance: Added step-by-step instructions on utilizing relative, path-safe markdown pull request comments.

v0.2.0 — Score Gating, Snapshots, and Delta Comparison

This release upgrades Recodey Shield from a scanner that outputs static reports into an interactive pipeline integration and incremental auditing suite:

• CI Gating & Exit Codes: Custom score thresholds (--fail-score-below) and severity level policies (--fail-on / --fail-on-new) mapped to standardized exit codes.
• Local Scan History Snapshots: Automatic, default-on snapshot rotations (latest.json and previous.json) to track project posture over time.
• Local Delta comparison: Instant analysis of consecutive runs to identify score drift, resolved items, newly introduced risks, and severity count changes inside delta.json without any extra flags.
• Visual PDF Export Strategy: A gorgeous offline visual HTML file (report.html) built with zero remote CDN dependencies, delegating printing/saving to native browser print workflows.
• Safe PR summaries: Relative, Markdown-escaped summaries (--pr-summary) scrubbed of absolute path structures or raw credential strings.

v0.1.9 — Report UX, HTML Report, and Security Fix Pack (Stable Release)

This release upgrades Recodey Shield from a scanner that outputs findings into a professional security reporting suite:

• Improved summary.md (Quick Status): A beginner-friendly, founder-ready overview containing an executive score card, launch readiness badges (Blocked, Needs Review, Ready), top blockers list, risk category counts, and dynamic "Quick Wins" (low-effort fixes like missing .gitignore or license definitions).
• Improved full-report.md (Detailed Audit): A structured, non-repetitive developer-focused report grouped by severity and then category. Suppresses empty checklists and eliminates duplicate license/config listings for easier scrolling.
• Security Fix Pack (review-pack.md): Fully revamped developer fix checklists organized file-by-file with rule explanations (what it means, why it is risky, how to fix/verify) and copy-pasteable safe code examples for eval(), JWT secrets, Express rate limits, Helmet, and NestJS validation rules.
• Lightweight report.html (Visual Sharing & Printing): A gorgeous, responsive visual report built without any external CDN or remote asset dependencies. Designed to be opened directly in the browser offline and visually printed or saved as PDF locally.
• Improved advanced/report.json (Automation/Dashboard): Enriched JSON schemas adding toolVersion, schemaVersion, scoreExplanation, metrics, blockers, quick wins, and file reference maps for direct ingestion in custom pipelines.
• PDF Export Decision: Direct heavy dependencies (such as Puppeteer or Playwright) are omitted to maintain a fast installation size. Professional PDF output is easily accomplished by using the browser's native "Print to PDF" on report.html. Direct CLI PDF generation remains future optional work and is not bundled in the core package.

v0.1.8 — Framework-Aware Code Security Scanner (Previous Stable Release)

• Universal Pathing & Exclusions: All finding file paths are normalized relative to the scan target using unified forward slashes. Traversal strictly avoids scanning pre-existing report directories, and findings located outside the scan target are automatically ignored.
• Gated Framework-Specific Scanners: NestJS and Express scanners run ONLY when their target framework is confidently detected, preventing noisy or irrelevant warnings in generic libraries or unrelated codebases.
• Evidence-Based Framework Detection: Identifies NestJS, Express, React, and Next.js using precise signal combinations (package dependencies, active imports, file name cues, and route/decorator patterns) to avoid keyword false positives.
• Generic Deduplication Layer: Automatically resolves overlapping findings (e.g., preferring sast.eval-usage over ast.eval, or sast.command-exec over ast.child-process-dangerous), selecting the highest-quality rule family, score, and explanation.
• NestJS Security Checks: Specialized checks for missing @UseGuards() authorization guards, @Public() access bypasses, insecure global ValidationPipe configurations (e.g. missing whitelist or having disableErrorMessages: true), untyped request bodies (@Body() body: any), and decorated vs undecorated properties in Data Transfer Objects (DTOs).
• Express Security Checks: Context-aware verification for missing helmet protection headers, wildcard CORS configuration (origin: "*"), credential-sharing wildcard CORS, missing express-rate-limit setups, unprotected API login routes, and unguarded API routes when auth middleware is defined elsewhere.
• JWT & Token Checks: Hardcoded JWT secrets, weak signature keys, logical fallback weaknesses (process.env.JWT_SECRET || "weak"), missing signature expiration times (expiresIn), and dangerous "none" algorithm allowances.
• General SAST Engine: Recursive AST checks identifying eval() usage, dynamic code constructors (new Function), dangerous child_process.exec command building with request context, raw SQL concatenation/template injections (SELECT ... + req.body), MongoDB query injections (find(req.body)), dynamic path traversals (fs.readFile), and prototype pollution key leaks.
• Gitignore Rule Validation: Scans git configuration rules and groups missing sensitive exclusions (like .env, node_modules, *.pem, recodey-shield-report/) into a single high-priority warning.
• Deep Dependency CVE Audit: Deep scans package lockfiles against known vulnerabilities locally via a timeout-guarded JSON parser, offline by default and running only when the --deep flag is explicitly supplied.

Offline Limits

All standard scans run 100% locally and fully offline. Source code never leaves your machine. For deep dependency audits querying active CVE databases, only package names and versions are sent, never source code.

Stable Reference Guidelines

Public guides, scripts, and deployment instructions stable-reference [email protected], the current published version on npm.

Potential Risk Static Analysis Guidelines

Static analysis involves uncertainty when reading raw source code without executing it. When a potential issue is detected but cannot be 100% verified deterministically, Recodey Shield marks it as a "Potential Risk" with a medium or low confidence level. Confirmed deterministic vulnerabilities (like hardcoded secrets or direct eval calls) are flagged with High Confidence. Developers should review both categories in generated reports to ensure robust coverage.

Deep Scan Command Execution

By default, scans run fully offline to guarantee privacy and maximum performance. To perform a deep vulnerability audit querying active dependency databases, run:

npx [email protected] scan --deep .

Scanner Coverage & Roadmap

Current Coverage (v0.1.8 / v0.1.9)

• Framework-Aware SAST: Multi-signal NestJS and Express detection and context scanning.
• Secrets and hardcoded credentials: High-entropy token checks, specific vendor patterns (Stripe, Groq, OpenAI, etc.), and database URLs.
• Committed .env files: Detection of committed .env files in git repositories.
• .env.example safety behavior: Verification of .env.example templates, skipping generic placeholders while flagging real secrets.
• Config risks: Stricter .gitignore checks, wildcard CORS policies, dangerous debug modes, and weak JWT secrets.
• JWT/Cryptographic sign validation: expiration verification, insecure algorithms (none), and dynamic fallback blocks.
• Report visibility metrics: Detailed breakdowns of files scanned, skipped, and code languages checked.
• Deep vulnerability audit: Offline-safe CVE locker parsing,Timeout guarded deep scanning.
• Upgraded Reporting Suite (v0.1.9): Rich summary card dashboards, non-repetitive developer audits, detailed Security Fix Packs, machine-readable JSON endpoints, and offline printable HTML files.

Current Coverage (v0.2.0 / v0.2.1)

• CI Gating & Exit Codes: Custom score thresholds and exit code policies.
• Local Scan History Snapshots & Delta: Automatic tracking of posture and drift between consecutive runs.
• Lightweight Visual PDF Strategy: Browser-native printing of responsive HTML report.
• Framework-Aware SAST: NestJS and Express context scanning and secret checks.

v0.3.1 — Experimental Project Intelligence Preview

v0.3.1 adds an experimental Project Intelligence preview behind an opt-in CLI flag.

• Opt-In Flag: --experimental-project-intelligence allows users to generate local, evidence-backed architectural and readiness reports. This flag and the npm version-pinned command (such as npx [email protected] scan --quick . --experimental-project-intelligence) are fully available in v0.3.1 and above.
• Isolated Report: Output is written as a separate file (project-intelligence.md) to avoid breaking existing reports or CI parsers.
• Evidence-Based Guidance: Infers archetype classification, maps tech stack and directories, and computes launch readiness scores without modifying standard security scans or changing exit codes.

npm Package

| | | |---|---| | Package name | recodey-shield | | Current version | 0.4.2 | | Install | npm install -g recodey-shield | | Use without installing | npx [email protected] scan --quick . | | Registry | npmjs.com/package/recodey-shield |

Safe Installation & Package Trust

To ensure maximum security and developer trust when integrating Recodey Shield into your workflows:

• Zero Lifecycle Install Hooks: The package contains absolutely no preinstall, postinstall, prepare, or other automatic lifecycle scripts. The Recodey Shield package itself defines no install-time lifecycle hooks, so installing it does not run Recodey Shield-controlled install scripts on your workstation or CI runner.
• Dependency Containment: All workspace modules are compiled and bundled into a single self-contained binary file (dist/index.js) using esbuild. The published package only depends externally on commander (for command parsing), minimizing dependencies and reducing supply-chain risk.
• Packaged Compliance Assets: The published [email protected] package includes both the README.md and the MIT LICENSE, facilitating compliance verification.
• No Automatic Publish/Update Scripts: There are no automated background update scripts or hidden telemetry queries. Version checking and upgrades are entirely manual.

Quick Start

Recommended First Run

To evaluate a new project in less than 30 seconds, run these standard commands in your project root:

npx [email protected] --version
npx [email protected] doctor
npx [email protected] scan --quick .
npx [email protected] scan --quick . --review-pack
npx [email protected] scan --quick . --ci --fail-on high
npx [email protected] scan --quick . --output ./security-report

• --version confirms the installed package version.
• doctor checks environment readiness.
• scan --quick . runs a fast local security scan.
• --review-pack generates a shareable review pack.
• --ci --fail-on high is useful for CI gating.
• --output changes the report output folder.

Use without installing (npx)

# Check version
npx [email protected] --version

# Check environment
npx [email protected] doctor

# Quick security scan
npx [email protected] scan --quick .

# Deep vulnerability audit scan
npx [email protected] scan --deep .

# Generate founder/security review pack
npx [email protected] scan --quick . --review-pack

# Save reports to custom folder
npx [email protected] scan --quick . --output ./security-report

# Run with experimental Project Intelligence enabled (version-pinned)
npx [email protected] scan --quick . --experimental-project-intelligence

# Run with experimental Project Intelligence enabled (latest)
npx recodey-shield@latest scan --quick . --experimental-project-intelligence

Install globally

npm install -g recodey-shield

recodey-shield --version
recodey-shield doctor
recodey-shield scan --quick .
recodey-shield scan --deep .
recodey-shield scan --quick . --review-pack
recodey-shield scan --quick . --output ./security-report

# Run with experimental Project Intelligence enabled
recodey-shield scan --quick . --experimental-project-intelligence

# Uninstall
npm uninstall -g recodey-shield

From source (for contributors)

git clone https://github.com/kruturaj-20/security.git recodey-shield
cd recodey-shield
pnpm install
pnpm build
node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js scan --quick .
node packages/cli/dist/index.js scan --deep .

Available Commands

| Command | Description | |---|---| | recodey-shield --version | Shows installed CLI version | | recodey-shield doctor | Checks if environment is ready | | recodey-shield scan --quick . | Scans current project locally and offline | | recodey-shield scan --deep . | Scans project and performs deep dependency vulnerability audit | | recodey-shield scan --quick . --review-pack | Generates founder/security review pack | | recodey-shield scan --quick . --output ./security-report | Saves reports to custom folder | | recodey-shield scan --quick . --fail-on high --ci | CI scan with failure threshold | | recodey-shield scan --quick . --experimental-project-intelligence | Runs scan with experimental Project Intelligence report |

What Happens After a Scan

Recodey Shield generates reports in the recodey-shield-report/ folder by default.

Open this first: recodey-shield-report/summary.md

What gets generated?

• summary.md — short scan overview and next action.
• full-report.md — detailed developer-facing findings.
• review-pack.md — shareable security review pack when enabled.
• report.html — offline visual report opened in browser.
• advanced/report.json — machine-readable report data.
• advanced/report.sarif — SARIF output for compatible security tooling.
• history/latest.json — latest sanitized local snapshot.
• history/previous.json — previous sanitized local snapshot.
• history/delta.json — local comparison between latest and previous scans when available.
• recodey-shield-report/project-intelligence.md — experimental project layout, architecture, and readiness report when opted in.

Generated Files

| File | Primary Role & Audience | Description | |---|---|---| | recodey-shield-report/README.md | Guide & Safety Notes | Folder navigation guide, next steps, and scanner security disclaimers. | | recodey-shield-report/summary.md | Quick Status (Founders / PMs) | Executive scan summary containing security scores, readiness, blockers, and quick wins. | | recodey-shield-report/full-report.md | Detailed Audit (SecOps / Leads) | Detailed technical findings grouped by severity and category with why-it-matters reasons. | | recodey-shield-report/review-pack.md | Developer Fix Checklist (Devs) | Security Fix Pack organizing priority P0-P3 checklists, file references, and secure code snippets. | | recodey-shield-report/report.html | Visual Sharing & Print (Execs / Clients) | Responsive local visual report built for offline browsing, printing, or native browser PDF saving. | | recodey-shield-report/advanced/report.json | Automation & CI Dashboard | Enriched machine-readable JSON containing full metrics, blockers list, and score metadata. | | recodey-shield-report/advanced/report.sarif | CI/CD GitHub Integration | Standard SARIF format to seamlessly integrate security scans with GitHub Code Scanning. | | recodey-shield-report/history/latest.json | Local Scan History snapshot | Sanitized, privacy-safe JSON snapshot containing high-level score, metrics, and finding tracking signatures of the most recent scan. | | recodey-shield-report/history/previous.json | Local Scan History snapshot | Sanitized, privacy-safe JSON snapshot of the scan prior to the latest scan, rotated automatically. | | recodey-shield-report/project-intelligence.md | Heuristic Design & Architecture (Founders / Tech Leads) | Experimental Project Intelligence report detailing archetype classification, tech stack, API surfaces, missing production features, and launch readiness scores. |

[!TIP] review-pack.md is only generated when --review-pack is used. report.html opens directly in any browser offline. report.json is useful for automation pipelines. report.sarif integrates with GitHub Advanced Security.

Report History & Delta Comparison

Recodey Shield includes a local-first Report History & Delta Comparison engine to track code quality and security trends across scans without sending any data to external cloud databases.

Key Behaviors

• Enabled by Default: History snapshots and delta comparisons are automatically processed and saved inside the report output directory on every successful scan run.
• Automatic Rotation & Delta Compilation:
  • First Scan: latest.json is generated. Since no previous scan exists, delta generation is skipped.
  • Subsequent Scans: The existing latest.json is rotated to previous.json, and the new scan results are written to latest.json. Immediately after rotation, the engine automatically compares latest.json and previous.json to generate history/delta.json.
  • Fault-Tolerant Unlinking: If either history snapshot is missing, malformed, or has an unsupported schema, delta comparison is skipped and any stale delta.json or delta.tmp.json is actively deleted/removed from disk to prevent displaying out-of-date or misleading trend metrics.
• Opt-Out Option: To disable all history snapshot logging and delta comparison completely, pass the --no-history flag:

  recodey-shield scan --quick . --no-history

• Custom Report Directories: If a custom output directory is specified using --output <dir>, history snapshots and delta reports are stored under <custom-dir>/history/.
• CI & Exit Gate Safety: Snapshot rotation and delta generation are performed before the CLI checks CI threshold gates (--fail-on, --fail-score-below). Thus, even if the scan exits with error code 1 due to a threshold violation, the history snapshots and delta.json remain fully compiled and preserved as valid build artifacts in your pipeline.
• Local-Only & Privacy Boundary:
  • Runs 100% offline with zero network calls, API key parsing, authorization tokens, or external API/webhook postings (such as automatic GitHub/GitLab PR commenting).
  • Strict Sanitization: The delta engine reads strictly from history snapshots. It never parses report.json or raw scanner output, meaning it strictly excludes all proprietary source code, raw code snippets, matching evidence text, unredacted credentials/keys, and AI explanations.
  • Absolute Path Suppression: All file paths inside latest.json, previous.json, and delta.json are double-normalized to safe, target-relative forward-slash paths (e.g. src/server.ts), stripping workstation-specific prefixes (like C:\Users\ or /home/runner/).
• Comparing Baselines vs. Historical Delta:
  • Baseline (New/Existing): Used for Accepted Risk management inside recodey-shield.baseline.json. It tracks long-term ignored findings or false positives so that CI pipelines only fail on newly added violations relative to the team's official policy.
  • Historical Delta (New/Resolved/SeverityChanged): Used for consecutive-run drift auditing inside history/delta.json. It compares the scan just completed against the immediate prior scan run, showing executive score drift, launch readiness shifts, severity count changes, resolved issues, newly introduced findings, and findings whose severity level was updated.

Delta Schema Structure (delta.json)

The compiled delta file contains:

• score: Previous score, latest score, numeric change, and trend direction (improved, regressed, unchanged).
• readiness: Previous readiness level, latest readiness level, and boolean indicating if it changed.
• severityCounts: Change offsets for critical, high, medium, and low issues.
• issueDelta: Classified arrays of newIssues, resolvedIssues, existingIssues, and severityChangedIssues sorted deterministically by severity priority, ruleId, file, and line.
• humanSummary: Consumable sentences describing scan trends (e.g., ["Security score improved by 10 points (from 85 to 95).", "Resolved 2 issues."]).
• recommendedNextAction: Quick executive priority instruction.

[!NOTE] Static Analysis & Risk Policy Warning Static analysis checks source code heuristics offline without executing it. It represents potential risk indicators and launch-readiness guidelines. It cannot guarantee 100% security, absolute accuracy, or replace expert penetration testing. All historical delta reports and security findings require human verification.

Visual PDF Strategy & Export Guide

Recodey Shield features an elegant, responsive, and completely offline-first visual HTML report inside recodey-shield-report/report.html. This file serves as the canonical source for gorgeous security dashboards and executive printouts without compromising speed, security, or data privacy.

The Lightweight Zero-Dependency PDF Design

Traditional CLI tools often bundle massive headless browser automation suites (like Puppeteer or Playwright) to auto-generate PDF files. However, this architectural choice introduces significant trade-offs:

1. Extreme Package Size Bloat: Bundling a headless Chromium browser adds 100MB+ to the package install footprint.
2. Installation Failures: Heavy browser binaries regularly crash or fail to build in Windows CMD terminal sessions, locked-down virtual environments, or firewalled enterprise CI runners.
3. Slow Setup Times: Installs drag from seconds into several minutes.

To prevent dependency bloat and guarantee absolute runtime reliability across any operating system, Recodey Shield delegates PDF compilation to the user's browser. The generated report.html is fully self-contained (using inline styles and SVG vector icons) with zero dependencies on remote CDNs, web fonts, or internet connections. Your source code and findings stay 100% private and local.

Direct headless CLI PDF export remains a post-v0.2.0 roadmap option to be shipped as a standalone companion package (@recodey/shield-pdf) so that only users who specifically request automated CLI exports need to pay the package size penalty.

Step-by-Step Browser Print & Save Flow

To export a gorgeous, print-ready PDF from your scan:

🌐 Chrome / Edge / Chromium

1. Open recodey-shield-report/report.html directly in your browser.
2. Press Ctrl + P (Windows/Linux) or Cmd + P (macOS) to open the print dialog.
3. Set the Destination to Save as PDF.
4. (Optional) Click More settings and ensure Background graphics is enabled to keep the premium security score gradients.
5. Click Save and select your output folder.

🦊 Firefox

1. Open recodey-shield-report/report.html in Firefox.
2. Press Ctrl + P or Cmd + P (or click the Firefox Menu -> Print...).
3. Set the print destination to Save to PDF.
4. Click Save and choose your file destination.

🧭 Safari

1. Open recodey-shield-report/report.html in Safari.
2. Choose File -> Export as PDF... (or press Cmd + P and select Save as PDF from the print options).
3. Specify your output filename and click Save.

CI/CD Artifact Persistence & Visual Review

In automated CI/CD pipelines, we recommend uploading the entire recodey-shield-report/ folder as a build artifact. Reviewers and security leads can download the directory, open report.html locally, and visually print or inspect the report offline.

Here are complete, production-ready recipes for popular CI platforms:

🚀 GitHub Actions

- name: Archive Recodey Shield reports
  uses: actions/upload-artifact@v4
  with:
    name: recodey-shield-report
    path: recodey-shield-report/

🦊 GitLab CI

artifacts:
  name: recodey-shield-report
  paths:
    - recodey-shield-report/
  expire_in: 1 week

This strategy ensures that security reviews are visual and actionable, while keeping all proprietary source code details, line numbers, and findings entirely isolated inside your secure infrastructure.

Release & Testing Tools

These commands are for maintainers and contributors preparing future releases:

• pnpm release:check — Full pipeline: build, lint, tests, typecheck, smoke tests, package install tests, and npm pack --dry-run.
• pnpm test:smoke — Runs the CLI against a temporary directory to verify commands and reporting.
• pnpm test:package — Packs the CLI, installs it in an isolated temp project, and verifies all commands work outside the monorepo.
• pnpm release:npm-check — Validates package metadata, tarball contents, CLI version consistency, git cleanliness, and npm auth status.

See the full publish checklist in RELEASE_CHECKLIST.md.

Working

• Local-first privacy guarantee: Source code never leaves your machine. No source code upload.
• Fast file traversal (ignoring node_modules, standard build artifacts, binaries, and large files).
• Configuration support: Customizable via recodey-shield.config.json with CLI flags seamlessly overriding config options.
• Scanners:
  • AST Scanner: Deeply analyzes JS/TS files using the TypeScript Compiler API to detect usage of eval(), new Function(), dangerous child_process execution, and disabled TLS/CORS verifications.
  • Secret Scanner: Detects OpenAI, Stripe, Groq, Razorpay, Firebase keys, generic JWT/Bearer tokens, and passwords while redacting sensitive information.
  • Config Scanner: Detects missing .gitignore, committed .env, dangerous debug flags, and wildcard CORS.
  • Dependency Scanner: Provides comprehensive dependency intelligence. Analyzes lockfile drift, mismatching lockfiles, risky versions (wildcards, tags, local/git URLs), and dangerous lifecycle scripts.
  • License Risk Audit: Integrated with the Dependency Scanner, it detects unknown and missing licenses, as well as high-risk copyleft licenses (like GPL/AGPL). Note: This is risk detection, not legal advice.
• Policy Engine & Custom Rules: Customize which rules are enabled, adjust severity levels, exclude paths, set CI thresholds, and define your own Custom Rules using safe regular expressions via recodey-shield.config.json.
• External OSV Database Integration: Optionally verifies your package.json dependencies against the OSV DB. OSV queries only send package names and versions—never source code or sensitive content.
• Report generation: Terminal summary, JSON, Markdown, and SARIF export compatible with GitHub Security.
• AI Explanation Mode (--ai): Generates safe, plain English explanations for detected security issues. Uses strict Issue Packets to guarantee that source code and full repository content are never uploaded, and aggressively redacts raw secrets from snippets.
• CI-friendly Baselines and Accepted Risk: Track issues deterministically across scans via issue fingerprints. Allows teams to generate a baseline file (recodey-shield.baseline.json) to acknowledge existing issues (including accepted risks and false positives) so CI pipelines only fail on newly introduced vulnerabilities.

Limitations

• The Dependency Scanner focuses on local analysis for Lockfile Drift and Dependency Risk (dependency.unpinned-version, dependency.risky-source, dependency.risky-lifecycle-script, dependency.missing-lockfile, dependency.multiple-lockfiles, dependency.lockfile-mismatch).
• License risk checking is local and MVP. It does not perform deep legal parsing, it merely warns for unknown, missing, or copyleft-indicating licenses (license.unknown, license.missing, license.copyleft-risk).
• Full registry metadata intelligence (like maintainer/package age analysis, deprecated package checks, latest version comparisons) are planned for future phases. There are no new external registry network calls in Phase 8.
• Not 100% security guarantee. Recodey Shield is not a replacement for expert penetration testing.
• AST Scanner is currently early quality and focuses on known explicit dangerous function calls.
• OSV API currently only utilizes package.json versions. Deeper full-tree lockfile resolution is planned for the future.
• AI Explanations are guidance, not guaranteed truth. They are not a replacement for manual security review.
• AI Explanation currently relies on an OpenAI-compatible provider and the RECODEY_SHIELD_AI_API_KEY environment variable.

Roadmap (Phase 10+)

• Automated direct CLI PDF export (as an optional companion package to avoid core CLI footprint bloat).
• Full Web Dashboard.

Report Output & Structure

By default, Recodey Shield creates a single clean, developer-friendly output folder named recodey-shield-report/ in your current working directory. You can customize this folder using the --output <dir> CLI option.

Folder Structure

recodey-shield-report/
  ├── README.md               # Folder guide, next steps, and security warning
  ├── summary.md              # Beginner-friendly executive scan summary (Read this first!)
  ├── full-report.md          # Detailed technical developer findings
  ├── review-pack.md          # Security Fix Pack / developer checklist (if --review-pack is enabled)
  ├── report.html             # Gorgeous visual dashboard for offline sharing/printing
  └── advanced/
      ├── report.json         # Enriched machine-readable scan results
      ├── report.sarif        # Standard SARIF for GitHub Code Scanning
      └── review-pack.json    # Accompanying review metadata (if --review-pack is enabled)

Recommended Gitignore Snippet

Since security reports contain details about your codebase's internal structure and potential risks, we highly recommend adding the default report folder to your .gitignore:

# Recodey Shield Security Reports
recodey-shield-report/

Recommended Adoption Flow

To successfully onboard your engineering team or project, we recommend following this step-by-step local-first adoption strategy:

1. Run Locally: Execute a quick scan using npx [email protected] scan --quick . to evaluate your current security posture.
2. Review Reports: Open the generated report.html locally in your browser and check summary.md to see the top prioritized vulnerabilities and quick wins.
3. Add Configuration File: Create a recodey-shield.config.json in your project root to exclude test directories and establish your baseline severity overrides.
4. Establish CI Score Threshold: Add a lenient CI score threshold (e.g. policy.ci.failScoreBelow: 60) in your config or directly via --fail-score-below 60 inside your build pipeline to get started without breaking existing builds.
5. Generate PR Summary Artifacts: Use --pr-summary ./pr-summary.md on pull request checks to create secure, local-first review markdown summaries to guide developers.
6. Tighten Gates Over Time: Gradually resolve identified security issues and raise the score gate (e.g., to 80 or 85) and enforce rules using --fail-on-new high to ensure your main branch stays secure.

[!NOTE] Local-First & Offline Privacy: All configuration parsing, CI threshold evaluations, baseline matches, and PR summary generation workflows run 100% offline and fully locally on your machine or runner. No credentials, tokens, repository secrets, or source code are ever uploaded to any cloud service.

Setup

Ensure you have Node.js v20+ and pnpm installed.

pnpm install
pnpm build

# You can optionally link the CLI globally
cd packages/cli && pnpm link --global

npm / npx troubleshooting

If you run into version resolution issues or commands are not recognized:

Old version running

If npx continues to run an older cached version of the tool, check active registry tags or clear local package caches:

npm cache verify
npm view recodey-shield version
npm dist-tag ls recodey-shield
npx --yes recodey-shield@latest --version

Command not recognized

If the recodey-shield executable cannot be found in your shell context after global installation, use explicit package execution:

npm exec --yes --package=recodey-shield@latest -- recodey-shield --version
npm exec --yes --package=recodey-shield@latest -- recodey-shield doctor

Need reproducible version

For continuous integration (CI) and reproducible builds, we recommend pinning the specific version rather than using @latest:

• Use [email protected] instead of @latest when you want a pinned stable version in CI.

Configuration & Policy Engine

Introduction to Configuration

A local-first security tool should adapt seamlessly to your development workflows. Recodey Shield reads options from an optional recodey-shield.config.json file located in your project root, or from a custom path supplied via the --config <file> option.

Using a configuration file allows you to:

• Enforce standard gates: Ensure all developers and CI/CD pipelines run with identical policies.
• Filter noise: Safely ignore specific files, folders, categories, or rules.
• Define custom rules: Search for organization-specific debug keys or bad practices safely.

How CLI Flags and Config Values Interact

To ensure maximum flexibility in local experiments and CI pipelines:

1. Config File Defaults: The config file acts as the baseline blueprint for your scanning policy.
2. CLI Override Precedence: Any option passed directly via a CLI flag (e.g. --output, --fail-on, --max-file-size, --fail-score-below, --fail-on-new) overrides the corresponding value defined in the configuration file.

Example Local Config (recodey-shield.config.json)

For standard day-to-day local development, this config focuses on high-speed scanning while keeping local assets structured:

{
  "output": "./recodey-shield-report",
  "maxFileSize": 10485760,
  "includeTests": false,
  "ignorePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**"
  ],
  "osv": {
    "enabled": false
  },
  "policy": {
    "disabledRules": [
      "ast.dangerously-set-innerhtml"
    ],
    "disabledCategories": [
      "Styling"
    ],
    "excludePaths": [
      "tests/mocks/",
      "test-env-"
    ],
    "severityOverrides": {
      "config.wildcard-cors": "high",
      "dependency.lifecycle-script": "medium"
    }
  }
}

Example CI Config (recodey-shield.config.json)

For continuous integration workflows, you can enforce security thresholds and exit gates automatically:

{
  "maxFileSize": 5242880,
  "osv": {
    "enabled": true
  },
  "policy": {
    "disabledRules": [],
    "excludePaths": [
      "**/tests/**"
    ],
    "ci": {
      "failOn": "critical",
      "failOnNew": "high",
      "failScoreBelow": 80
    }
  }
}

Supported Configuration Keys

• output (string): Custom relative folder to save generated reports.
• maxFileSize (number): Maximum size of a file in bytes to scan (e.g., 5242880 for 5MB).
• includeTests (boolean): Whether to run security scans on test files.
• ignorePatterns (string[]): Glob patterns of folders/files to bypass completely.
• osv (object): OSV vulnerability database settings.
  • osv.enabled (boolean): Enable deep vulnerability analysis against the OSV catalog locally.
• failOn (string): Default severity to fail scans (e.g., high, critical).
• failScoreBelow (number): Default security score threshold to trigger failures.
• policy (object): Advanced audit policies.
  • policy.disabledRules (string[]): Individual scanner rule IDs to silence.
  • policy.disabledCategories (string[]): Whole scanner groups to ignore.
  • policy.severityOverrides (object): Custom severity mapping (e.g. {"config.wildcard-cors": "high"}).
  • policy.excludePaths (string[]): Path substrings to exclude from policy evaluations.
  • policy.ci (object): Automated CI gate configurations.
    • policy.ci.failOn (string): CI threshold gate matching failOn.
    • policy.ci.failOnNew (string): CI threshold gate to fail strictly on newly introduced issues.
    • policy.ci.failScoreBelow (number): CI threshold gate matching failScoreBelow.
• customRules (array): User-defined custom regular expressions to check.

Customizing Policy

The policy section allows teams to adapt the engine to their specific needs without modifying core scanner logic:

• disabledRules: Silence specific findings that are noisy or irrelevant.
• disabledCategories: Turn off entire classes of checks.
• severityOverrides: Elevate or reduce the severity of a finding.
• excludePaths: Ignore specific files or directories from being evaluated.
• ci.failOn & ci.failOnNew: Define strict failure thresholds for your CI pipelines that apply automatically.

Custom Rules

You can implement your own simple, regex-based custom rules to find patterns specific to your organization (like internal debug tokens, bad practices, etc.).

• Custom rules are safe by default and do not execute arbitrary JavaScript.
• Custom rule IDs act as the identity for your findings across baselines and reports.
• Like all Recodey Shield checks, Custom Rules will never expose raw secrets in reports.

Example recodey-shield.config.json:

{
  "policy": {
    "disabledRules": [
      "ast.dangerously-set-innerhtml"
    ],
    "disabledCategories": [
      "Styling"
    ],
    "severityOverrides": {
      "config.wildcard-cors": "high",
      "dependency.lifecycle-script": "medium"
    },
    "excludePaths": [
      "tests/mocks/",
      "test-env-"
    ],
    "ci": {
      "failOn": "critical",
      "failOnNew": "high"
    }
  },
  "customRules": [
    {
      "id": "company.no-debug-token",
      "title": "Debug token should not be committed",
      "severity": "high",
      "category": "custom",
      "description": "Detects debug token usage in source code",
      "filePatterns": ["**/*.ts", "**/*.js"],
      "regex": "DEBUG_TOKEN",
      "message": "Debug token reference found. Please use production keys.",
      "enabled": true
    }
  ]
}

Usage

Check if your environment is ready:

recodey-shield doctor

Basic scans:

# Scan current directory
recodey-shield scan --quick

# Scan specific path
recodey-shield scan --quick ./my-project

Flags

# Enable safe AI Explanations for issues (requires RECODEY_SHIELD_AI_API_KEY)
export RECODEY_SHIELD_AI_API_KEY=your_key_here
recodey-shield scan --quick --ai

# Run in CI mode for concise terminal output and strict exit codes
recodey-shield scan --quick --ci

# Provide an explicit config path (otherwise looks for recodey-shield.config.json in project root)
recodey-shield scan --quick --config ./my-custom-config.json

# Generate JSON output only
recodey-shield scan --quick --json

# Save reports to a custom directory
recodey-shield scan --quick --output ./custom-report-folder

# Enable experimental Project Intelligence analysis
recodey-shield scan --quick --experimental-project-intelligence

# Generate a structured security review pack with --review-pack
recodey-shield scan --quick --review-pack

# Specify a custom review pack output location
recodey-shield scan --quick --review-pack --review-pack-output ./custom-report-folder/security-review.md

# Fail CI/CD pipelines if high/critical issues are found
recodey-shield scan --quick --fail-on high

# Include hidden files in the scan
recodey-shield scan --quick --include-hidden

# Adjust max file size (in bytes)
recodey-shield scan --quick --max-file-size 10485760

# --- Baseline Management ---

# Load an existing baseline file to filter and mark issues as existing/new
recodey-shield scan --quick --baseline ./recodey-shield.baseline.json

# Write or update the baseline file with the current scan's findings
recodey-shield scan --quick --update-baseline

# Fail CI ONLY if NEW issues (not in baseline) match or exceed a severity threshold
recodey-shield scan --quick --ci --baseline ./recodey-shield.baseline.json --fail-on-new high

Baseline and Accepted Risk

Recodey Shield allows teams to manage existing security issues, preventing CI pipelines from constantly failing due to legacy issues while staying protected against new vulnerabilities.

Issue Fingerprints

Recodey Shield assigns a deterministic fingerprint (e.g., rs_a1b2c3d4e5f6) to every detected issue based on stable fields (like scanner name, category, relative file path, and normalized snippets).

How CI Teams Should Use Baseline

1. First Run (Generate the Baseline) Run a scan locally and update the baseline. This will create a recodey-shield.baseline.json file.

recodey-shield scan --quick --update-baseline

Commit this file to your repository. Note: Baseline files only contain fingerprints and metadata—they do not contain raw secrets, snippets, or source code, and are completely safe to commit.

2. Review and Accept Risk If you have findings that are false positives or intentional, open recodey-shield.baseline.json and change their status from active to accepted-risk or false-positive. Note: Teams should regularly review their accepted risk decisions.

3. Configure CI Pipeline In your CI workflow, run Recodey Shield using the baseline and use --fail-on-new to strictly fail your pipeline only when a newly introduced issue meets the severity threshold.

CI Thresholds and Exit Codes

Recodey Shield is designed to be fully integrated into continuous integration (CI) workflows. It supports strict failure policies, baseline-driven scanning, and customizable exit codes.

Exit Code Isolation

To allow CI pipelines to separate security findings from tooling, configuration, or environment crashes, Recodey Shield implements clean, isolated exit codes:

• 0 (Success): The scan completed successfully, and no configured security thresholds or exit gates were violated. Findings may still be present but did not trigger a gate.
• 1 (Security Threshold Violated): The scan completed successfully, but one or more configured security thresholds (such as --fail-on, --fail-on-new, or --fail-score-below) was met or exceeded.
• 2 (Usage / Config / Runtime Error): The scan could not complete or parse options correctly due to syntax issues, a missing or invalid config file, malformed parameters, filesystem failures, or CLI runtime crashes.

CLI Gate Flags

• --ci: Enables CI mode, which optimizes console outputs for clean logging (hiding verbose counters) and prints an executive summary.
• --fail-on <severity>: Fails the scan (exit code 1) if any active issue of the specified severity or higher (e.g. critical, high, medium, low) is found.
• --fail-on-new <severity>: Fails the scan (exit code 1) strictly if any newly introduced (non-baselined) issues of this severity or higher are found. Existing issues in the baseline file do not fail.
• --fail-score-below <number>: Fails the scan (exit code 1) if the project's final security score drops below this threshold (0-100).
• --quiet: Silences all standard command outputs on stdout/stderr, making it ideal for clean log files, while keeping gates and report generation fully functional.
• --summary-only: Suppresses file traversal logs and outputs only the concise executive scan summary.

Reducing CI Log Noise

Continuous integration runner consoles are most readable when noise is minimized. Recodey Shield provides built-in options to optimize console logging without affecting scan operations or artifact generation:

• Summary-Only Console Output (--summary-only): Suppresses verbose file-by-file traversal logs, displaying only the final executive score, readiness status, and finding breakdown table:

  npx [email protected] scan --quick . --ci --summary-only

• Fully Quiet Mode (--quiet): Silences all outputs to stdout/stderr. Perfect for clean script wrappers or automation tasks, while CI threshold evaluation and report generation remain fully active:

  npx [email protected] scan --quick . --ci --quiet --fail-on high --output ./security-reports

Progressive Gating (Loose to Tight)

To prevent breaking active pipelines for engineering teams, we recommend a progressive adoption strategy:

1. Phase 1: Observation Mode (Loose Thresholds): Run scans in advisory mode without setting a threshold, or with a low gate like --fail-score-below 50 or --fail-on critical.
2. Phase 2: Baseline Existing Risks: Generate a recodey-shield.baseline.json file. Use --fail-on-new high to ensure no new high/critical risks are committed, while allowing legacy issues to be fixed over time.
3. Phase 3: Strict Gating: As issues are fixed, tighten the gate to --fail-score-below 85 and --fail-on high.

Configuration File Policy Gate Settings

You can add these configurations inside your recodey-shield.config.json file. CLI flags will dynamically take precedence and override these values:

{
  "policy": {
    "ci": {
      "failOn": "critical",
      "failOnNew": "high",
      "failScoreBelow": 80
    }
  }
}

Concrete Examples

1. Baseline + Incremental Severity Gating

Protect your main branch from any new high or critical risks, while allowing legacy issues to be resolved over time:

recodey-shield scan --quick --ci --baseline ./recodey-shield.baseline.json --fail-on-new high

2. Project Security Score Gating

Ensure your overall project security score (which deducts points based on vulnerabilities found) never drops below 85 points:

recodey-shield scan --quick --ci --fail-score-below 85

3. Fully Quiet Scan Mode

Generate all standard reports (summary.md, report.html, report.json, etc.) without printing anything to console stdout:

recodey-shield scan --quick --quiet --output ./security-reports

[!NOTE] Static Analysis & Potential Risks: Static analysis checks are local-first and run without executing source code. When a potential issue is detected but cannot be verified deterministically, it is flagged as a "Potential Risk" (medium/low confidence). Confirmed vulnerabilities are labeled High Confidence. Both are written to reports so developers can review. Local-First Privacy: All scans and reports are generated entirely locally. Even when running inside GitHub Actions, your code never leaves the runner environment.

GitHub Actions CI Template

Add this workflow definition to your repository at .github/workflows/recodey-shield.yml to automatically audit your codebase on every push and pull request:

name: Recodey Shield Security Scan

on:
  pull_request:
  push:
    branches: [main]

jobs:
  security-scan:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run Recodey Shield
        run: npx --yes recodey-shield@latest scan --quick . --ci --fail-on high

      - name: Upload Recodey Shield reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: recodey-shield-report
          path: recodey-shield-report/

• --fail-on high fails CI on high/critical findings.
• if: always() uploads reports even when the scan fails.
• Users can pin [email protected] instead of @latest for reproducible CI.

GitLab CI Template

Add this workflow job block to your .gitlab-ci.yml file to integrate Recodey Shield scans into your GitLab CI/CD pipelines:

recodey_shield_scan:
  image: node:20
  stage: test
  script:
    - npx --yes recodey-shield@latest scan --quick . --ci --fail-on high
  artifacts:
    when: always
    name: recodey-shield-report
    paths:
      - recodey-shield-report/
    expire_in: 1 week

• The report folder is saved as a CI artifact.
• Users can download artifacts and open report.html.
• when: always keeps reports available even when the scan fails.

GitHub Action Integration

Recodey Shield comes with a built-in GitHub Action to easily integrate security scanning into your CI/CD pipelines.

Example Workflow

Create a file in your repository at .github/workflows/recodey-shield.yml to automatically scan your code on every push and pull request.

name: Recodey Shield Security Scan

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install

      - name: Build project
        run: pnpm build

      - name: Run Recodey Shield Scan
        uses: ./.github/actions/recodey-shield
        with:
          path: .
          fail-on: critical
          output: ./recodey-shield-report
          quick: true
          # ai: true # Optional: Enables safe AI explanation mode

      - name: Upload Recodey Shield Reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: recodey-shield-reports
          path: |
            recodey-shield-report/README.md
            recodey-shield-report/summary.md
            recodey-shield-report/full-report.md
            recodey-shield-report/advanced/report.json
            recodey-shield-report/advanced/report.sarif

SARIF Output

When running Recodey Shield using the Action or CLI, it automatically generates a recodey-shield-report.sarif report inside the specified output directory. You can easily integrate this file with GitHub Advanced Security by uploading the SARIF file as an artifact.

Limitations

When running in CI mode or via the GitHub Action, remember the following limitations:

• AI Explanations require passing the RECODEY_SHIELD_AI_API_KEY to the runner environment securely via GitHub Secrets. If the key is missing in CI mode, the tool will gracefully ignore it rather than crashing.
• SARIF export natively integrates with GitHub Advanced Security, but this may require a GitHub Enterprise Server or GitHub Advanced Security license for private repositories depending on GitHub's policies.

Privacy Guarantee

Recodey Shield provides a local-first privacy guarantee:

• Source code is not uploaded. It never leaves your machine.
• Only safe, redacted issue packets are sent when using AI Explanation Mode (--ai).
• Full repository contents and raw secrets are strictly ignored and never sent.
• Baseline safety: The generated baseline file (recodey-shield.baseline.json) deliberately strips out raw secret values, snippets, and source code. It only contains necessary tracking metadata, making it completely safe to commit to version control.

PR Review Mode & GitHub Annotations

Recodey Shield can be integrated into GitHub and GitLab Pull Requests to scan only the files that have changed, emit findings as inline GitHub Actions annotations, and generate secure, local-only pull request summaries.

recodey-shield scan --quick --ci --changed-only --base-ref origin/main --head-ref HEAD --github-annotations --pr-summary ./recodey-shield-report/advanced/pr-summary.md

PR Scan Flags

• --changed-only: Scans strictly the files modified in the pull request branch.
• --base-ref <ref>: The base git branch or reference to compare against (automatically loads GITHUB_BASE_REF in GitHub Actions).
• --head-ref <ref>: The head git SHA or reference to compare (automatically loads GITHUB_SHA in GitHub Actions).
• --github-annotations: Emits inline warnings, errors, and notices directly onto the pull request diff layout inside GitHub.
• --pr-summary <file>: Generates a compact, highly secure pull request comment card inside the specified Markdown file.

Safe PR Comment Summary (--pr-summary)

The PR summary option compiles a secure, local-only Markdown report card that summarizes the scan results. It is built strictly offline, running 100% locally on your CI runner or workstation, and is heavily hardened to guarantee privacy and pipeline stability:

1. Secrets & Snippets Isolation: Absolute suppression of raw credentials, .env file contents, and source code fragments. It only lists finding severities, formatted rule names, and sanitized filenames.
2. Zero Absolute Path Leakage: All absolute workstation paths (C:\Users\...) and host runner directories (/home/runner/...) are stripped and mapped to clean, target-relative forward-slash paths (e.g. packages/core/src/index.ts).
3. Untrusted Markdown Escaping: All titles, file paths, and metadata strings are HTML-escaped and sanitized (escaping | table cells, HTML brackets <, >, and backticks) to prevent formatting corruption or Markdown injection.
4. Local-First Privacy & Zero Cloud Dependency: The PR summary is built strictly offline. It never auto-posts to external hosts, requires no GitHub tokens or API permissions, and never uploads your source code or scan details to any external cloud service.
5. Exit-Code Gate Survival: The summary is written to disk before CI severity/score thresholds are evaluated. If a scan exits with code 1 (gate failed) or score thresholds are violated, the PR summary remains fully preserved on disk for manual copy/pasting or pipeline log uploads.

To use the PR summary alongside CI score gates, simply combine the options:

npx [email protected] scan --quick . --ci --fail-score-below 80 --pr-summary ./pr-summary.md

What the Summary Includes:

• 🏆 Security Score Card: An overall project score (0-100) reflecting relative security health.
• 🚦 Launch Readiness State: A status signal indicating if launch is Blocked, Needs Review, or Ready.
• 📊 Findings Breakdown: A tabular tally of active findings by severity levels (Critical, High, Medium, Low).
• 🔄 Baseline Activity: An incremental overview of new, existing (ignored), and resolved issues.
• 🔍 Escaped Top Findings: A table showing the top 10 findings, clearly labeling their baseline status (New vs Existing).
• 📄 Portable Report Hyperlinks: Relative paths pointing directly to your local detailed reports.

CI Workflow Recipes

1. GitHub Actions Step Summary

Write the PR summary directly to the GitHub Action workflow run dashboard with a single command:

- name: Run Recodey Shield PR Scan
  run: npx [email protected] scan --quick --ci --changed-only --pr-summary $GITHUB_STEP_SUMMARY

2. GitHub Actions PR Comment and Reports Artifact

Generate annotations, save report suites, and compile the safe comment card for manual upload:

- name: Run Recodey Shield
  run: npx [email protected] scan --quick --ci --github-annotations --pr-summary ./pr-summary.md

- name: Upload Report Suite
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: recodey-shield-reports
    path: |
      recodey-shield-report/
      pr-summary.md

3. GitLab CI Artifact

Export findings for code quality pipelines:

recodey-shield-scan:
  stage: test
  script:
    - npx [email protected] scan --quick --ci --pr-summary pr-summary.md
  artifacts:
    name: recodey-shield-summary
    paths:
      - pr-summary.md
      - recodey-shield-report/
    when: always

[!NOTE] Static Analysis Warning: Static checks are local-first checks performed heuristically on codebase layouts and syntax without running code. Static analysis represents potential security indicators and launch assistance; it is not a replacement for comprehensive penetration testing or manual code audits.

Privacy & Git Limitations

• When scanning pull requests, configure your git checkout with fetch-depth: 0 so the runner environment has complete history to run diffs.
• If changed files cannot be detected, the scan will fail to prevent silent failures.

For an example of how to implement this in a GitHub Workflow, see .github/workflows/recodey-shield-pr.yml.example.

AI Security Review Pack

Recodey Shield allows developers and founders to generate an actionable, launch-readiness review pack using --review-pack. The review pack converts scanner findings into a structured document detailing executive summaries, top risks, fix priority roadmaps, category breakdowns, and a remediation checklist.

Features

• Deterministic Fallback: The review pack works entirely offline using deterministic local logic. If --ai is used but the API key is missing, it will gracefully fallback to deterministic output without crashing.
• AI Enrichment: If --ai is enabled and the RECODEY_SHIELD_AI_API_KEY is present, Recodey Shield will safely enrich the top 5 highest-risk findings with explanations and guidance.
• Launch Readiness Status: Automatically evaluates the project's readiness (Ready, Needs Review, or Blocked) based on critical vulnerabilities, CI thresholds, and new baseline findings.
• Privacy Guarantees: The review pack follows Recodey Shield's strict privacy rules. Only safe issue packets are sent for the top 5 findings. No full files or raw secrets are ever sent.

Usage

# Generate the review pack locally (Markdown and JSON metadata)
recodey-shield scan --quick --review-pack

# Generate the review pack and enrich with AI
export RECODEY_SHIELD_AI_API_KEY="your_key"
recodey-shield scan --quick --ai --review-pack

# Generate and save the review pack to a custom location
recodey-shield scan --quick --review-pack --review-pack-output ./my-reports/security-review.md

Outputs

When the --review-pack flag is used, Recodey Shield generates two files by default under the specified output directory:

• review-pack.md: The primary founder/security review Markdown document.
• advanced/review-pack.json: Accompanying machine-readable metadata payload.

Note: The review pack will be overwritten on each scan. Ensure you save historical artifacts in your CI/CD/PR pipelines as needed.

Experimental Project Intelligence

Starting with v0.3.1, Recodey Shield includes an experimental Project Intelligence preview. This opt-in feature compiles a focused, evidence-backed layout and architectural analysis of your project, pointing out structural patterns and readiness signals for moving to production.

The engine supports multiple project archetypes:

• Static websites (Astro, Jekyll, sitemap, HTML, index.html)
• Web apps (Vite, React, custom single-page apps)
• Backend APIs (Express, NestJS, server routing directories)
• Full-stack apps (Next.js, Remix, etc.)
• Mobile apps (React Native, iOS Info.plist, AndroidManifest.xml)
• npm packages (libraries with export mappings and entry points)
• CLI tools (Node binaries with shebang execution lines)
• AI apps (OpenAI dependencies, prompts directories)
• Monorepos (pnpm-workspace.yaml, Turborepo, sub-packages)
• Unknown / Needs-review projects (generic files or conflicting layout signals)

[!WARNING] Experimental Preview Notice Project Intelligence is currently in an experimental phase and is subject to change. It is disabled by default and is opt-in only. In this release, it must not be used as a stable CI verification pipeline or a replacement for expert security audits. It acts as heuristic guidance, not a security or production-readiness guarantee.

Command Usage

To run a scan with Project Intelligence enabled:

# Running without local installation (using the version-pinned release)
npx [email protected] scan --quick . --experimental-project-intelligence

# Running with the latest release
npx recodey-shield@latest scan --quick . --experimental-project-intelligence

# Running as a globally installed package
recodey-shield scan --quick . --experimental-project-intelligence

[!IMPORTANT] CLI-Only Activation Project Intelligence is currently activated strictly through the CLI flag --experimental-project-intelligence. It cannot be enabled via the recodey-shield.config.json configuration file in this experimental preview version.

[!NOTE] Version-Pinned Execution Note For reproducible CI/CD pipelines and stable execution, we recommend pinning the specific version: npx [email protected] scan --quick . --experimental-project-intelligence.

Report Output & Isolation

When the --experimental-project-intelligence flag is provided, the engine generates a separate, dedicated Markdown report file:

recodey-shield-report/project-intelligence.md

If a custom output directory is specified using the --output <dir> flag, the report is saved directly inside that folder: