envvars-scan

Scan codebases for environment variable usage across multiple languages and frameworks.

Installation

# Run directly with npx (no install needed)
npx @skyhook-io/envvars-scan .

# Or install globally
npm install -g @skyhook-io/envvars-scan

Requirements

• Node.js 18+
• Semgrep for code scanning: brew install semgrep

Usage

# Scan current directory
envvars-scan

# Scan specific path
envvars-scan ./src

# Scan a remote GitHub repo (clones to temp, scans, cleans up)
envvars-scan --repo facebook/react
envvars-scan -r vercel/next.js

# Keep cloned repo after scanning
envvars-scan --repo org/repo --keep

# Clone specific branch
envvars-scan --repo org/repo --branch develop

# Include lowercase config keys (not just uppercase env vars)
envvars-scan --all

# Include docker-compose.yml env vars (off by default)
envvars-scan --compose

# Include Kubernetes manifests (Deployments, ConfigMaps, Secrets)
envvars-scan --k8s

# Show detected values (sensitive values are masked)
envvars-scan --show-values

# Combine flags for full visibility
envvars-scan --k8s --show-values

# Output as JSON
envvars-scan --json

# Show parser warnings
envvars-scan -v

# Create custom config file
envvars-scan --init-config

# Compare against a git branch/commit (local use)
envvars-scan --diff origin/main
envvars-scan --diff HEAD~5

# Compare two JSON scan outputs (CI use)
envvars-scan compare base.json head.json

CI Integration

Detect env var changes in pull requests:

name: Env Vars Check
on:
  pull_request:
    branches: [main]

jobs:
  check-env-vars:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install semgrep
        run: pip install semgrep

      - name: Scan base branch
        run: |
          git checkout ${{ github.base_ref }}
          npx @skyhook-io/envvars-scan --json > /tmp/base.json

      - name: Scan PR branch
        run: |
          git checkout ${{ github.head_ref }}
          npx @skyhook-io/envvars-scan --json > /tmp/head.json

      - name: Compare env vars
        run: npx @skyhook-io/envvars-scan compare /tmp/base.json /tmp/head.json

What It Scans

Code Patterns (via Semgrep)

| Language | Patterns | |----------|----------| | Go | os.Getenv(), os.LookupEnv(), viper.Get*(), envconfig | | JavaScript/TypeScript | process.env, NestJS ConfigService, env() helpers | | Python | os.getenv(), os.environ, Django env()/config(), Flask, Pydantic | | Java | System.getenv(), Spring @Value, Environment.getProperty(), Quarkus @ConfigProperty, Dotenv.get() | | Kotlin | System.getenv(), Quarkus @ConfigProperty, Dotenv.get() | | Ruby | ENV[], ENV.fetch(), Rails credentials | | Rust | std::env::var(), env!() macro | | C# | Environment.GetEnvironmentVariable(), IConfiguration | | PHP | getenv(), $_ENV, Laravel env()/config() | | Scala | sys.env(), sys.env.get() |

Config Files (built-in regex scanner)

• Property files: application.properties, bootstrap.properties with ${VAR} or ${VAR:default} syntax (Spring, Quarkus)
• YAML files: application.yaml, application.yml with ${VAR} syntax
• .env files: Variable definitions like VAR_NAME=value (matches both .env* and *.env patterns)
• Dockerfiles: ENV and ARG declarations
• docker-compose.yml: Environment variable references (${VAR}) and definitions

Kubernetes Manifests (with --k8s flag)

• Deployments/StatefulSets/DaemonSets: env: sections with direct values
• ConfigMaps: data: key-value pairs
• Secrets: data: values (base64 decoded)

Value Detection

The scanner detects values from multiple sources:

| Source | Example | valueSource | |--------|---------|---------------| | Code defaults | process.env.PORT \|\| 3000 | code-default | | .env files | DATABASE_URL=postgres://... | dotenv | | Dockerfile ENV | ENV NODE_ENV=production | dockerfile-env | | Dockerfile ARG | ARG VERSION=1.0.0 | dockerfile-arg | | K8s Deployments | env: [{name: X, value: Y}] | k8s-deployment | | K8s ConfigMaps | data: {KEY: value} | k8s-configmap | | K8s Secrets | data: {KEY: base64} | k8s-secret | | Spring properties | ${VAR:default} | properties |

Security

When using --show-values, sensitive values are automatically masked for variable names matching: secret, password, key, token, api, auth, credential, private

Example output:

DATABASE_URL = postgres://localhost:5432/dev (dotenv)
API_KEY = sk****89 (dotenv)  # masked

Custom Patterns

Create .skyhook/envvars-scan.yaml in your project:

customPatterns:
  - id: my-helper
    description: "Custom env var helper"
    pattern: 'getEnvVar("$VAR", ...)'
    languages: [javascript, typescript]

# Additional directories to exclude
includeExcludePatterns:
  - "generated"
  - "third_party"

Programmatic Usage

import {
  scan,
  scanPropertyFiles,
  scanK8sManifests,
  uniqueEnvVarNames,
  groupByName,
  type EnvVar,
  type ValueSource
} from '@skyhook-io/envvars-scan';

// Full scan (semgrep + property files)
const result = await scan('./my-project', {
  filterUppercase: true,
});

console.log(uniqueEnvVarNames(result));

// Access values
for (const envVar of result.envVars) {
  console.log(envVar.name, envVar.value, envVar.valueSource);
}

// Property files only
const propertyVars = await scanPropertyFiles('./my-project');

// Kubernetes manifests
const k8sVars = await scanK8sManifests('./my-project');

EnvVar Type

interface EnvVar {
  name: string;
  file: string;
  line: number;
  language: string;
  pattern: string;
  value?: string;           // Detected value (if found)
  valueSource?: ValueSource; // Where the value came from
  isDefault?: boolean;       // Is this a default/fallback value?
}

Default Excludes

The following directories are excluded by default:

• node_modules, .next, dist, .git, vendor, build
• .mastra, coverage, __pycache__, .venv, venv, target

License

MIT