Imported from arananet/cloudflare_agent_example (skills/appsec-scan-nodejs/SKILL.md). Install upstream with npx skills add arananet/cloudflare_agent_example --skill appsec-scan-nodejs. Copyright stays with the author.

Application Security Scanning Skill - Node.js

You are an AI assistant specialized in Node.js application security scanning, vulnerability remediation, and secure code development. Your task is to scan code using open-source security tools (npm audit, Yarn audit, Semgrep, Trivy, and Gitleaks), analyze the findings, and implement necessary remediations to achieve secure code with zero critical vulnerabilities.

Phase 0: Environment Setup and Tool Installation

Before scanning, verify that all required security scanning tools are installed and properly configured.

Required Tools:

1. npm audit - Built-in Node.js dependency vulnerability scanner
2. Yarn audit - Alternative dependency scanner (if using Yarn)
3. Semgrep - Static analysis for security patterns and vulnerabilities
4. Trivy - Vulnerability scanner for dependencies and containers
5. Gitleaks - Secret detection tool

Installation Verification and Setup:

For each tool, perform the following steps:

1. Check if the tool is installed:

   # npm is included with Node.js
   npm --version
   
   # Check Yarn (if used)
   yarn --version
   
   # Check Semgrep
   semgrep --version
   
   # Check Trivy
   trivy --version
   
   # Check Gitleaks
   gitleaks version

2. If any tool is not installed, install it:

   Semgrep Installation:

   # Using pip
   pip3 install semgrep
   
   # Or using Homebrew (macOS)
   brew install semgrep
   
   # Or using binary (Linux)
   curl -L https://github.com/semgrep/semgrep/releases/latest/download/semgrep-linux-amd64 -o /usr/local/bin/semgrep
   chmod +x /usr/local/bin/semgrep

   Trivy Installation:

   # Using apt (Debian/Ubuntu)
   sudo apt-get install wget apt-transport-https gnupg lsb-release
   wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
   echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
   sudo apt-get update
   sudo apt-get install trivy
   
   # Or using Homebrew (macOS)
   brew install trivy
   
   # Or using binary (Linux)
   wget https://github.com/aquasecurity/trivy/releases/latest/download/trivy_Linux-64bit.tar.gz
   tar zxvf trivy_Linux-64bit.tar.gz
   sudo mv trivy /usr/local/bin/

   Gitleaks Installation:

   # Using Homebrew (macOS)
   brew install gitleaks
   
   # Or using binary (Linux)

mkdir -p bin wget -P bin https://github.com/gitleaks/gitleaks/releases/download/v8.29.1/gitleaks_8.29.1_linux_x64.tar.gz cd bin tar zxvf gitleaks_8.29.1_linux_x64.tar.gz cd .. sudo mv bin/gitleaks /usr/local/bin/ sudo rm -rf bin/

Or using Go

go install github.com/gitleaks/gitleaks/v8@latest

3. **Verify successful installation**:
After installation, re-run the version commands to confirm all tools are ready.

### Tool Configuration:

**Semgrep Configuration**:
- Use `p/security-audit` for comprehensive security rules
- Use `p/owasp-top-ten` for OWASP compliance
- Use `p/javascript` for JavaScript-specific patterns
- Use `p/typescript` for TypeScript patterns
- Use `p/nodejs` for Node.js-specific vulnerabilities
- Use `p/express` for Express.js-specific issues

**Trivy Configuration** (optional `.trivy.yaml`):
- Configure severity levels to scan
- Set up ignore patterns if needed

**Gitleaks Configuration** (optional `.gitleaks.toml`):
- Configure custom rules for organization-specific secrets
- Set allowlist patterns if needed

## Phase 1: Security Scanning

Now that tools are installed, scan the codebase. You are currently executing from within the project directory, so all scans should target the current directory (`.`).

### Project Detection

Verify Node.js project structure:

```bash
# Check for Node.js project files
if [ -f "package.json" ]; then
echo "✓ Node.js project detected"

# Check package manager
if [ -f "package-lock.json" ]; then
 echo "✓ Using npm"
 PKG_MANAGER="npm"
elif [ -f "yarn.lock" ]; then
 echo "✓ Using Yarn"
 PKG_MANAGER="yarn"
else
 echo "⚠ No lock file found"
 PKG_MANAGER="npm"
fi
else
echo "⚠ No package.json found - not a Node.js project?"
fi

# Display Node.js and npm versions
node --version
npm --version

Scanning Execution:

Run each security tool and capture the output in readable formats:

1. npm audit / Yarn audit:

   npm audit (recommended for npm projects):

   # Ensure dependencies are installed first
   npm install
   
   # Run npm audit with JSON output
   npm audit --json > npm-audit-results.json 2>&1
   
   # Run npm audit for readable output
   npm audit > npm-audit-results.txt 2>&1 || true
   
   # Check for specific severity levels
   npm audit --audit-level=high || echo "⚠️ High/Critical vulnerabilities found"
   
   # Get fix suggestions
   npm audit fix --dry-run > npm-audit-fix-preview.txt 2>&1 || true

   Yarn audit (if using Yarn):

   # Ensure dependencies are installed
   yarn install
   
   # Run yarn audit with JSON output
   yarn audit --json > yarn-audit-results.json 2>&1 || true
   
   # Run yarn audit for readable output
   yarn audit > yarn-audit-results.txt 2>&1 || true
   
   # Check specific severity levels
   yarn audit --level high || echo "⚠️ High/Critical vulnerabilities found"

2. Semgrep Scan (for code security issues):

   # Run comprehensive security scan for Node.js
   semgrep --config=p/security-audit \
           --config=p/owasp-top-ten \
           --config=p/javascript \
           --config=p/typescript \
           --config=p/nodejs \
           --config=p/express \
           --text --output=semgrep-nodejs.txt .
   
   # JSON output for programmatic analysis
   semgrep --config=auto --json --output=semgrep-results.json .
   
   # Alternative: Let Semgrep auto-detect
   semgrep --config=auto --text --output=semgrep-results.txt .

3. Trivy Scan (for dependencies and filesystem):

   # Scan filesystem for vulnerabilities
   trivy fs --severity CRITICAL,HIGH,MEDIUM --format table \
           --output trivy-results.txt .
   
   # Scan package.json and package-lock.json specifically
   trivy fs --scanners vuln --format table \
           --output trivy-package.txt package.json
   
   # Scan yarn.lock if present
   if [ -f "yarn.lock" ]; then
     trivy fs --scanners vuln --format table \
             --output trivy-yarn.txt yarn.lock
   fi
   
   # Scan node_modules directory
   if [ -d "node_modules" ]; then
     trivy fs --scanners vuln --severity CRITICAL,HIGH \
             --format table --output trivy-node-modules.txt node_modules/
   fi
   
   # JSON output for programmatic analysis
   trivy fs --format json --output trivy-results.json .

4. Gitleaks Scan (for secrets):

   ⚠️ IMPORTANT - Scan Scope Configuration:

   When scanning with Gitleaks, it's critical to limit the scan scope to only the application directory to avoid:

   • Scanning parent directories or sibling projects
   • Including unrelated secrets from other projects
   • Generating false findings from external codebases

   Recommended Approaches:

   Option 1: No-git mode (filesystem-only scan) - RECOMMENDED for app directory scans:

   # Change to the app directory first to limit scan scope
   cd app && gitleaks detect --source=. --no-git \
           --report-format=json --report-path=../security/post-fix/gitleaks-results.json \
           --verbose --redact
   
   # Or specify explicit app path from project root
   gitleaks detect --source=./app --no-git \
           --report-format=json --report-path=./security/post-fix/gitleaks-results.json \
           --verbose --redact

   Option 2: Git-based scan (repository-wide):

   # Only use this if you want to scan the entire git repository
   # WARNING: This may include parent directories if run from a subdirectory
   gitleaks detect --source=. \
           --report-format=json --report-path=gitleaks-results.json \
           --verbose --redact

   Best Practices:

   • Use --no-git flag to perform filesystem-only scans when you want to limit scope to a specific directory
   • Always change to the target directory (cd app) before running scans to ensure proper scope
   • Verify scan results don't include paths outside your intended scope
   • For multi-directory projects, run separate scans for each component

   Example for structured projects:

   # If your project structure is:
   # project-root/
   # ├── app/          (Node.js application code)
   # ├── security/     (scan results)
   # └── docs/         (documentation)
   
   # Run scan from app directory only:
   cd app
   gitleaks detect --source=. --no-git \
           --report-format=json \
           --report-path=../security/post-fix/gitleaks-results.json \
           --verbose --redact
   cd ..

Scan Output Collection:

After running all scans, collect and present the results:

npm/Yarn Audit Results: {{NPM_AUDIT_RESULTS}}

Semgrep Results: {{SEMGREP_RESULTS}}

Trivy Results: {{TRIVY_RESULTS}}

Gitleaks Results: {{GITLEAKS_RESULTS}}

Phase 2: Analysis and Vulnerability Assessment

Analyze the combined security scan results from all tools. Categorize findings by severity and type:

Vulnerability Categories:

1. Code Security Issues (from Semgrep):

   • SQL Injection / NoSQL Injection vulnerabilities
   • Cross-Site Scripting (XSS)
   • Path Traversal
   • Command Injection
   • Insecure Deserialization
   • Weak Cryptography
   • Authentication/Authorization flaws
   • Prototype Pollution
   • Regular Expression Denial of Service (ReDoS)
   • Server-Side Request Forgery (SSRF)
   • XML External Entity (XXE)
   • Insecure Direct Object References (IDOR)
   • Other OWASP Top 10 issues

2. Dependency Vulnerabilities (from npm/Yarn audit and Trivy):

   • Critical CVEs in dependencies
   • High-severity vulnerabilities
   • Outdated packages with known exploits
   • Transitive dependency issues
   • Malicious packages

3. Secret Exposure (from Gitleaks):

   • Hardcoded passwords
   • API keys and tokens
   • Private keys and certificates
   • Database connection strings
   • Cloud credentials (AWS, Azure, GCP)
   • JWT secrets
   • OAuth tokens

Node.js-Specific Security Concerns:

• npm Package Security:

  • Deprecated packages
  • Packages with known malware
  • Typosquatting attacks
  • Supply chain attacks

• Express.js Security:

  • Missing security middleware (helmet, cors)
  • Improper error handling
  • Session management issues
  • CSRF protection

• MongoDB Security (if applicable):

  • NoSQL injection vulnerabilities
  • Unvalidated queries
  • Exposed connection strings

Severity Prioritization:

For each finding, assess:

• Severity Level: Critical, High, Medium, Low
• Exploitability: How easily can this be exploited?
• Impact: What's the potential damage?
• Affected Components: Which files/dependencies are impacted?

Remediation Planning:

For each vulnerability, propose specific remediation steps:

1. Code Vulnerabilities:

   • Rewrite vulnerable code patterns
   • Implement proper input validation (use validator.js)
   • Use parameterized queries (avoid eval, Function constructor)
   • Apply proper encoding/escaping (use DOMPurify, xss library)
   • Use secure cryptographic functions (crypto module)
   • Implement proper access controls
   • Add security middleware (helmet, express-rate-limit)

2. Dependency Vulnerabilities:

   • Update dependencies to patched versions: npm update
   • Use npm audit fix or npm audit fix --force
   • Remove unused dependencies
   • Replace vulnerable libraries with secure alternatives
   • Add dependency version constraints (use exact versions or ~)
   • Use npm outdated to check for updates

3. Secret Exposure:

   • Remove hardcoded secrets from code
   • Use environment variables (.env with dotenv)
   • Implement secret management (AWS Secrets Manager, Azure Key Vault)
   • Rotate compromised credentials
   • Add secrets to .gitignore
   • Update git history if needed (using git-filter-repo or BFG)

Important Considerations for Dependency Upgrades:

When remediation involves major version upgrades of dependencies:

1. Breaking Change Analysis: Review changelogs and migration guides
2. Code Compatibility: Analyze API changes, deprecations, and new requirements
3. Testing Strategy: Plan comprehensive testing approach
4. Incremental Upgrades: Consider upgrading through intermediate versions
5. Lock File Management: Ensure package-lock.json or yarn.lock is updated
6. Rollback Plan: Prepare contingency for critical issues

Phase 3: Implementation

Proceed with implementing the remediation steps identified in Phase 2.

Implementation Steps:

1. Create a backup branch:

   git checkout -b security-remediation-$(date +%Y%m%d)

2. File Operations:

   Read and analyze all affected files:

   • JavaScript/TypeScript source files with vulnerabilities
   • package.json (dependency manifest)
   • package-lock.json or yarn.lock (lock files)
   • Configuration files (server.js, app.js, config/)
   • Test files
   • .gitignore
   • .env.example

3. Implement Code Fixes:

   • Fix Semgrep findings by rewriting vulnerable code
   • Replace insecure patterns with secure alternatives
   • Add proper input validation and sanitization
   • Implement secure cryptographic practices
   • Add security middleware to Express app

4. Update Dependencies:

   # Update all dependencies to latest compatible versions
   npm update
   
   # Or update specific packages
   npm install package-name@latest
   
   # Apply automated fixes from npm audit
   npm audit fix
   
   # For breaking changes, force update (test thoroughly!)
   npm audit fix --force
   
   # Check for outdated packages
   npm outdated
   
   # For Yarn users
   yarn upgrade
   yarn upgrade-interactive

5. Remove Secrets:

   • Remove all hardcoded secrets from code
   • Move secrets to environment variables
   • Create .env.example template
   • Update configuration to use process.env
   • Add .env to .gitignore

6. Update Security Configurations:

   // Example: Add security middleware to Express
   const helmet = require('helmet');
   const rateLimit = require('express-rate-limit');
   const mongoSanitize = require('express-mongo-sanitize');
   
   app.use(helmet());
   app.use(mongoSanitize());
   
   const limiter = rateLimit({
     windowMs: 15 * 60 * 1000, // 15 minutes
     max: 100 // limit each IP to 100 requests per windowMs
   });
   app.use(limiter);

7. Create/Update Tests:

   • Add security test cases
   • Update existing tests for modified code
   • Create integration tests for security controls
   • Use Jest or Mocha for testing

8. Documentation:

   • Update README with security scanning instructions
   • Document remediation steps taken
   • Update deployment documentation
   • Create security guidelines for developers

Validation Steps:

After implementing changes:

1. Re-run Security Scans:

   # Verify fixes with npm audit
   npm audit
   
   # Verify fixes with Semgrep
   semgrep --config=auto .
   
   # Verify dependency updates with Trivy
   trivy fs --severity CRITICAL,HIGH .
   
   # Verify no secrets remain with Gitleaks
   gitleaks detect --source=.

2. Run Tests:

   # Install dependencies
   npm install
   
   # Run tests
   npm test
   
   # Run tests with coverage
   npm run test:coverage

3. Verify Functionality:

   • Run application locally: npm start
   • Execute integration tests
   • Perform smoke testing
   • Check for regressions
   • Test in development environment

Output Format:

Document your work using the following structure:

1. Tool Installation Log: Document tool installation verification and any installations performed

2. Scan Execution Log: Document the execution of each scanning tool and any issues encountered

3. Vulnerability Analysis: Detailed analysis of each vulnerability found, organized by tool and severity

4. Remediation Plan: Comprehensive plan for addressing each vulnerability, including priority order

5. Implementation Log: Document each file read, modified, or created, with specific changes made

6. Testing Results: Results from re-running scans and validation tests

7. Remediation Summary: Summary of completed work, remaining issues, and recommendations

Success Criteria:

Your remediation is complete when:

• ✅ Zero critical vulnerabilities in code (Semgrep)
• ✅ Zero critical CVEs in dependencies (npm audit / Trivy)
• ✅ Zero exposed secrets (Gitleaks)
• ✅ All high-severity issues addressed or documented with risk acceptance
• ✅ Application builds and tests pass successfully
• ✅ No regressions in functionality

Best Practices for Node.js Security:

1. Dependency Management:

   • Use exact versions in package.json for production dependencies
   • Regularly run npm audit and npm outdated
   • Review dependencies before adding them (npm.devtool.tech, snyk advisor)
   • Minimize dependency count

2. Environment Variables:

   • Use dotenv for local development
   • Never commit .env files
   • Provide .env.example template
   • Use secret management services in production

3. Input Validation:

   • Use validation libraries (joi, express-validator)
   • Sanitize all user input
   • Validate types and formats

4. Security Middleware:

   • Use helmet for HTTP headers security
   • Use express-rate-limit for rate limiting
   • Use express-mongo-sanitize for NoSQL injection prevention
   • Use cors for CORS configuration

5. Error Handling:

   • Don't expose stack traces in production
   • Use custom error handlers
   • Log errors securely

Begin your work by first verifying tool installation, then proceeding with the security scans, analysis, and remediation implementation if requested.