@danielszlaski/envguard 0.1.0

package/src/parser/serverlessParser.ts

@@ -0,0 +1,146 @@
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+
+export interface ServerlessEnvEntry {
+  key: string;
+  valueExpression: string; // e.g., "${ssm:/path}" or "hardcoded-value"
+  isReference: boolean; // true if it references SSM, secrets manager, etc.
+  source: string; // file path
+  lineNumber?: number;
+}
+
+// CloudFormation intrinsic function types for js-yaml
+const CF_SCHEMA = yaml.FAILSAFE_SCHEMA.extend([
+  new yaml.Type('!Ref', { kind: 'scalar', construct: (data) => ({ Ref: data }) }),
+  new yaml.Type('!GetAtt', { kind: 'scalar', construct: (data) => ({ 'Fn::GetAtt': data }) }),
+  new yaml.Type('!GetAtt', { kind: 'sequence', construct: (data) => ({ 'Fn::GetAtt': data }) }),
+  new yaml.Type('!Join', { kind: 'sequence', construct: (data) => ({ 'Fn::Join': data }) }),
+  new yaml.Type('!Sub', { kind: 'scalar', construct: (data) => ({ 'Fn::Sub': data }) }),
+  new yaml.Type('!Sub', { kind: 'sequence', construct: (data) => ({ 'Fn::Sub': data }) }),
+  new yaml.Type('!ImportValue', { kind: 'scalar', construct: (data) => ({ 'Fn::ImportValue': data }) }),
+  new yaml.Type('!Select', { kind: 'sequence', construct: (data) => ({ 'Fn::Select': data }) }),
+  new yaml.Type('!Split', { kind: 'sequence', construct: (data) => ({ 'Fn::Split': data }) }),
+  new yaml.Type('!FindInMap', { kind: 'sequence', construct: (data) => ({ 'Fn::FindInMap': data }) }),
+  new yaml.Type('!GetAZs', { kind: 'scalar', construct: (data) => ({ 'Fn::GetAZs': data }) }),
+  new yaml.Type('!Base64', { kind: 'scalar', construct: (data) => ({ 'Fn::Base64': data }) }),
+  new yaml.Type('!Equals', { kind: 'sequence', construct: (data) => ({ 'Fn::Equals': data }) }),
+  new yaml.Type('!Not', { kind: 'sequence', construct: (data) => ({ 'Fn::Not': data }) }),
+  new yaml.Type('!And', { kind: 'sequence', construct: (data) => ({ 'Fn::And': data }) }),
+  new yaml.Type('!Or', { kind: 'sequence', construct: (data) => ({ 'Fn::Or': data }) }),
+  new yaml.Type('!If', { kind: 'sequence', construct: (data) => ({ 'Fn::If': data }) }),
+  new yaml.Type('!Condition', { kind: 'scalar', construct: (data) => ({ Condition: data }) }),
+]);
+
+export class ServerlessParser {
+  /**
+   * Parse a serverless.yml file and extract environment variables
+   * from the provider.environment section
+   */
+  parse(filePath: string): Map<string, ServerlessEnvEntry> {
+    const envVars = new Map<string, ServerlessEnvEntry>();
+
+    if (!fs.existsSync(filePath)) {
+      return envVars;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const doc = yaml.load(content, { schema: CF_SCHEMA }) as any;
+
+      if (!doc || typeof doc !== 'object') {
+        return envVars;
+      }
+
+      // Extract from provider.environment
+      const providerEnv = doc.provider?.environment;
+      if (providerEnv && typeof providerEnv === 'object') {
+        for (const [key, value] of Object.entries(providerEnv)) {
+          // Only include uppercase env var names (convention)
+          if (this.isValidEnvVarName(key)) {
+            const valueStr = String(value);
+            envVars.set(key, {
+              key,
+              valueExpression: valueStr,
+              isReference: this.isReference(valueStr),
+              source: filePath,
+            });
+          }
+        }
+      }
+
+      // Also check for function-level environment variables
+      const functions = doc.functions;
+      if (functions && typeof functions === 'object') {
+        for (const [funcName, funcConfig] of Object.entries(functions)) {
+          const funcEnv = (funcConfig as any)?.environment;
+          if (funcEnv && typeof funcEnv === 'object') {
+            for (const [key, value] of Object.entries(funcEnv)) {
+              if (this.isValidEnvVarName(key)) {
+                const valueStr = String(value);
+                // Don't overwrite if already exists from provider level
+                if (!envVars.has(key)) {
+                  envVars.set(key, {
+                    key,
+                    valueExpression: valueStr,
+                    isReference: this.isReference(valueStr),
+                    source: `${filePath} (function: ${funcName})`,
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error parsing ${filePath}:`, error);
+    }
+
+    return envVars;
+  }
+
+  /**
+   * Check if a value references external sources like SSM, Secrets Manager, etc.
+   */
+  private isReference(value: string): boolean {
+    if (typeof value !== 'string') {
+      return false;
+    }
+
+    // Check for common serverless variable patterns
+    const referencePatterns = [
+      /\$\{ssm:/,           // SSM Parameter Store
+      /\$\{aws:reference/,  // AWS reference
+      /\$\{file\(/,         // File reference
+      /\$\{self:custom\./,  // Custom variables
+      /\$\{opt:/,           // CLI options
+      /\$\{env:/,           // Environment variables
+      /\$\{cf:/,            // CloudFormation outputs
+    ];
+
+    return referencePatterns.some(pattern => pattern.test(value));
+  }
+
+  /**
+   * Validate if a key is a valid environment variable name
+   */
+  private isValidEnvVarName(key: string): boolean {
+    // Environment variables should typically be uppercase with underscores
+    // But we'll be flexible and accept mixed case
+    return /^[A-Z_][A-Z0-9_]*$/i.test(key);
+  }
+
+  /**
+   * Find all serverless.yml files in a directory
+   */
+  async findServerlessFiles(rootDir: string): Promise<string[]> {
+    const { glob } = await import('glob');
+
+    const files = await glob('**/serverless.{yml,yaml}', {
+      cwd: rootDir,
+      ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'],
+      absolute: true,
+    });
+
+    return files;
+  }
+}

package/src/scanner/codeScanner.ts

@@ -0,0 +1,148 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+import { ServerlessParser } from '../parser/serverlessParser';
+
+export class CodeScanner {
+  private rootDir: string;
+  private excludePatterns: string[];
+  private serverlessParser: ServerlessParser;
+
+  constructor(rootDir: string, excludePatterns: string[] = ['node_modules', 'dist', 'build', '.git']) {
+    this.rootDir = rootDir;
+    this.excludePatterns = excludePatterns;
+    this.serverlessParser = new ServerlessParser();
+  }
+
+  async scan(): Promise<Map<string, string[]>> {
+    const envVars = new Map<string, string[]>();
+
+    // Scan for JavaScript/TypeScript files
+    const files = await glob('**/*.{js,ts,jsx,tsx,mjs,cjs}', {
+      cwd: this.rootDir,
+      ignore: this.excludePatterns.map(p => `**/${p}/**`),
+      absolute: true,
+    });
+
+    for (const file of files) {
+      const vars = await this.scanFile(file);
+      for (const varName of vars) {
+        const relativePath = path.relative(this.rootDir, file);
+        if (!envVars.has(varName)) {
+          envVars.set(varName, []);
+        }
+        envVars.get(varName)!.push(relativePath);
+      }
+    }
+
+    // Also scan serverless.yml files for environment variable definitions
+    const serverlessFiles = await this.findServerlessFiles();
+    for (const file of serverlessFiles) {
+      const vars = this.scanServerlessFile(file);
+      for (const [varName, entry] of vars.entries()) {
+        const relativePath = path.relative(this.rootDir, file);
+        if (!envVars.has(varName)) {
+          envVars.set(varName, []);
+        }
+        envVars.get(varName)!.push(`${relativePath} (serverless config)`);
+      }
+    }
+
+    return envVars;
+  }
+
+  async scanFile(filePath: string): Promise<Set<string>> {
+    const envVars = new Set<string>();
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+
+      // Pattern 1: process.env.VAR_NAME
+      const processEnvPattern = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+      let match;
+
+      while ((match = processEnvPattern.exec(content)) !== null) {
+        envVars.add(match[1]);
+      }
+
+      // Pattern 2: process.env['VAR_NAME'] or process.env["VAR_NAME"]
+      const processEnvBracketPattern = /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"\]]/g;
+
+      while ((match = processEnvBracketPattern.exec(content)) !== null) {
+        envVars.add(match[1]);
+      }
+
+      // Pattern 3: Destructuring - const { VAR_NAME } = process.env
+      const destructuringPattern = /const\s+\{\s*([^}]+)\s*\}\s*=\s*process\.env/g;
+
+      while ((match = destructuringPattern.exec(content)) !== null) {
+        const vars = match[1].split(',').map(v => v.trim().split(':')[0].trim());
+        vars.forEach(v => {
+          if (/^[A-Z_][A-Z0-9_]*$/.test(v)) {
+            envVars.add(v);
+          }
+        });
+      }
+
+    } catch (error) {
+      console.error(`Error scanning file ${filePath}:`, error);
+    }
+
+    return envVars;
+  }
+
+  async findEnvFiles(): Promise<string[]> {
+    const envFiles = await glob('**/.env', {
+      cwd: this.rootDir,
+      ignore: this.excludePatterns.map(p => `**/${p}/**`),
+      absolute: true,
+    });
+
+    return envFiles;
+  }
+
+  async findServerlessFiles(): Promise<string[]> {
+    const serverlessFiles = await glob('**/serverless.{yml,yaml}', {
+      cwd: this.rootDir,
+      ignore: this.excludePatterns.map(p => `**/${p}/**`),
+      absolute: true,
+    });
+
+    return serverlessFiles;
+  }
+
+  scanServerlessFile(filePath: string): Map<string, any> {
+    return this.serverlessParser.parse(filePath);
+  }
+
+  async scanByDirectory(): Promise<Map<string, Map<string, string[]>>> {
+    // Returns a map of directory -> (varName -> file locations)
+    const dirMap = new Map<string, Map<string, string[]>>();
+
+    // Scan for JavaScript/TypeScript files
+    const files = await glob('**/*.{js,ts,jsx,tsx,mjs,cjs}', {
+      cwd: this.rootDir,
+      ignore: this.excludePatterns.map(p => `**/${p}/**`),
+      absolute: true,
+    });
+
+    for (const file of files) {
+      const vars = await this.scanFile(file);
+      const fileDir = path.dirname(file);
+      const relativePath = path.relative(this.rootDir, file);
+
+      for (const varName of vars) {
+        if (!dirMap.has(fileDir)) {
+          dirMap.set(fileDir, new Map());
+        }
+        const varMap = dirMap.get(fileDir)!;
+        if (!varMap.has(varName)) {
+          varMap.set(varName, []);
+        }
+        varMap.get(varName)!.push(relativePath);
+      }
+    }
+
+    return dirMap;
+  }
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+export interface EnvUsage {
+  varName: string;
+  locations: string[];
+}
+
+export interface EnvDefinition {
+  varName: string;
+  value?: string;
+  comment?: string;
+  source?: 'dotenv' | 'serverless' | 'both';
+  isReference?: boolean; // For serverless variables that reference external sources
+}
+
+export interface Issue {
+  type: 'missing' | 'unused' | 'undocumented';
+  varName: string;
+  details: string;
+  locations?: string[];
+}
+
+export interface ScanResult {
+  issues: Issue[];
+  usedVars: Map<string, string[]>;
+  definedVars: Set<string>;
+  exampleVars: Set<string>;
+}

package/test-project/.envguardrc.json

@@ -0,0 +1,7 @@
+{
+  "ignoreVars": [
+    "STAGE",
+    "OKTA_API_PATH"
+  ],
+  "strict": false
+}

package/test-project/src/lambda1/.env.example

@@ -0,0 +1,11 @@
+# Auto-generated by envguard
+# Do not put actual secrets in this file - use .env instead
+
+# Used in: test-project/src/lambda1/handler.js
+# Format: your-secret-here
+CUSTOM_KEY=
+
+# Used in: test-project/src/lambda1/handler.js
+# Format: your-secret-here
+STRIPE_SECRET_KEY=
+

package/test-project/src/lambda1/handler.js

@@ -0,0 +1,14 @@
+const stripe = require('stripe');
+
+const { STRIPE_SECRET_KEY, CUSTOM_KEY } = process.env;
+
+async function createPayment(amount) {
+  const stripeClient = stripe(STRIPE_SECRET_KEY);
+
+  return await stripeClient.paymentIntents.create({
+    amount,
+    currency: 'usd',
+  });
+}
+
+module.exports = { createPayment };

package/test-project/src/lambda2/.env.example

@@ -0,0 +1,9 @@
+# Auto-generated by envguard
+# Do not put actual secrets in this file - use .env instead
+
+# Used in: test-project/src/lambda2/handler.js
+OKTA_CLIENT_ID=
+
+# Used in: test-project/src/lambda2/handler2.js
+OKTA_DEV_CLIENT_ID=
+

package/test-project/src/lambda2/handler.js

@@ -0,0 +1,11 @@
+
+const OKTA_KEY = process.env.OKTA_CLIENT_ID;
+
+
+module.exports.getPermissions = async (event) => {
+    return {
+        statusCode: 200,
+        body: JSON.stringify({ message: `Your OKTA_CLIENT_ID is ${OKTA_KEY}` }),
+    };
+
+};

package/test-project/src/lambda2/handler2.js

@@ -0,0 +1,13 @@
+
+const OKTA_KEY = process.env.OKTA_DEV_CLIENT_ID;
+
+const client = new SecretsManagerClient({ region: process.env.AWS_REGION });
+
+
+module.exports.getPermissions = async (event) => {
+    return {
+        statusCode: 200,
+        body: JSON.stringify({ message: `Your OKTA_CLIENT_ID is ${OKTA_KEY}` }),
+    };
+
+};

package/test-project/src/lambda2/serverless.yml

@@ -0,0 +1,50 @@
+service: ${self:app}-lambda2
+app: my-app
+
+custom:  
+  cors-config:
+    origins:
+      - '*'
+    headers:
+      - Content-Type
+      - X-Amz-Date
+      - Authorization
+      - X-Api-Key
+      - X-Amz-Security-Token
+      - X-Amz-User-Agent
+      - token
+      - env
+      - provider      
+    allowCredentials: false  
+  
+  secrets_INTERNAL_KEYS: ${ssm:/aws/reference/secretsmanager/${self:app}/${opt:stage, self:provider.stage}/internal-keys}
+
+provider:
+  name: aws
+  runtime: nodejs20.x
+  memorySize: 8192
+  tags:
+    Product: ${opt:stage, self:provider.stage}-${self:app}
+  profile: abc
+  stage: dev
+  region: eu-central-1
+  deploymentBucket:
+    name: ${self:app}-deployment
+  versionFunctions: false
+  timeout: 29
+  environment:
+    NODE_ENV: ${file(./.env.yml):${opt:stage, self:provider.stage}.NODE_ENV}
+    STAGE: ${opt:stage, self:provider.stage}
+    OKTA_CLIENT_ID: ${self:custom.secrets_INTERNAL_KEYS.okta_client_id}
+    OKTA_API_PATH: ${self:custom.secrets_INTERNAL_KEYS.okta_api_path}
+
+functions:
+  getPermissions:
+    handler: handler.getPermissions
+    description: 'Retrieves a list of all permissions available in the system.'
+    events:
+      - http:
+          path: /permissions
+          method: get
+          cors: ${self:custom.cors-config}         
+

package/test-project/src/payment/.env.example

@@ -0,0 +1,23 @@
+# Auto-generated by envguard
+# Do not put actual secrets in this file - use .env instead
+
+# Used in: test-project/src/payment/server.ts
+# Format: your-api-key-here
+API_KEY=
+
+# Used in: test-project/src/payment/server.ts
+# Format: postgresql://user:pass@host:5432/db
+DATABASE_URL=
+
+# Used in: test-project/src/payment/server.ts
+# Format: 3000
+PORT=
+
+# Used in: test-project/src/payment/payment.js
+# Format: your-secret-here
+STRIPE_SECRET_KEY=
+
+# Used in: test-project/src/payment/payment.js
+# Format: your-secret-here
+STRIPE_WEBHOOK_SECRET=
+

package/test-project/src/payment/payment.js

@@ -0,0 +1,14 @@
+const stripe = require('stripe');
+
+const { STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET } = process.env;
+
+async function createPayment(amount) {
+  const stripeClient = stripe(STRIPE_SECRET_KEY);
+
+  return await stripeClient.paymentIntents.create({
+    amount,
+    currency: 'usd',
+  });
+}
+
+module.exports = { createPayment };

package/test-project/src/payment/server.ts

@@ -0,0 +1,11 @@
+import express from 'express';
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+const DATABASE_URL = process.env.DATABASE_URL;
+const API_KEY = process.env.API_KEY;
+
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+  console.log(`Database: ${DATABASE_URL}`);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}