dev-shield

dev-shield is a comprehensive Security Posture Management Tool and pre-flight scanner designed specifically to secure your local Node.js development environment.

With the rise of supply-chain attacks, threat actors increasingly target developer machines by injecting malicious payloads into configuration files, dependencies, and lockfiles. dev-shield acts as an active safeguard, analyzing your workspace and actively monitoring runtime network connections before your dev server runs.

Key Features

• Static Application Security Testing (SAST): Parses configuration files (Tailwind, Next.js, Vite) and core entry points using an Abstract Syntax Tree (AST) to detect code obfuscation, forbidden system module invocations, and dynamic code execution (e.g., eval).
• Dependency & Typosquatting Check: Scans your package.json for known typosquatting packages and suspicious postinstall scripts containing malicious commands.
• Lockfile Integrity Analyzer: Analyzes package-lock.json to ensure that resolved tarball URLs point to standard, trusted registries, preventing package hijacking.
• Hardcoded Secret Scanner: Scans your .env and source code for accidentally hardcoded secrets (AWS Keys, Slack Tokens, GitHub PATs).
• Runtime Network Monitoring (Monkey-Patching): Injects a pre-load script before the dev server starts to monitor http, https, and net outbound traffic. Unrecognized domains are blocked by default to prevent data exfiltration.
• CI/CD Ready: Supports JSON report generation for seamless integration with GitHub Actions or GitLab CI.

Installation

Install the package globally or locally as a dev dependency:

# Global install (Recommended for standalone usage)
npm install -g @oktan-lab/dev-shield

# Local install (As a dev dependency in your project)
npm install -D @oktan-lab/dev-shield

Demo: Detecting Obfuscated Payloads

When dev-shield detects obfuscated malware in your configurations (e.g. tailwind.config.js), it immediately aborts the execution before your development server even starts:

⚡oktan >> npm run dev

> [email protected] dev
> npx @oktan-lab/dev-shield/dev-shield next dev --turbopack

[dev-shield] Starting security analysis...

 [dev-shield] SECURITY VULNERABILITIES DETECTED 

[AST] tailwind.config.js
  - Line 501 has an unusual length (16357 characters).

[AST] tailwind.config.js
  - Dynamic require() detected, commonly used by malware loaders.

 EXECUTION ABORTED: Security threats detected in your workspace! 

Setup & Configuration

You can generate the default configuration file (.dev-shield.json) by running the initialization command:

npx @oktan-lab/dev-shield/dev-shield init

This will create a .dev-shield.json file in your project root:

{
  "networkMode": "block",
  "whitelistedDomains": [
    "localhost",
    "127.0.0.1",
    "vercel.com",
    "supabase.co",
    "supabase.com",
    "github.com"
  ],
  "customRules": []
}

• networkMode: Set to "warn" if you only want to log network violations instead of blocking them.
• whitelistedDomains: Add your trusted external API domains here so your application can reach them during development.

Usage

Use dev-shield as a wrapper in front of your usual commands.

If your original command is next dev, use:

npx @oktan-lab/dev-shield/dev-shield next dev

If dev-shield determines the workspace is safe, it will immediately execute next dev under its runtime network monitor. If a threat is detected, the process is automatically aborted (exit code 1).

Integration via package.json scripts

This is the recommended approach. Add the dev-shield prefix to your dev or start scripts.

{
  "scripts": {
    "dev": "dev-shield next dev",
    "build": "dev-shield next build"
  }
}

CI/CD Reporting

To run a scan-only check and generate a JSON report (without spawning a dev server), use:

dev-shield --scan-only --report json

This will generate a dev-shield-report.json file in your workspace containing the security analysis results.

Git Hook Integration (Example with Husky)

Use as a pre-commit hook wrapper to ensure you do not commit malware from compromised dependencies.

npx husky add .husky/pre-commit "npx @oktan-lab/dev-shield/dev-shield --scan-only"

License

MIT © 2026 oktan-lab/dev-shield