@kairosinternational/watchman 0.1.0

package/src/scanners/secrets-exposure/patterns/secret-signatures.ts

@@ -0,0 +1,78 @@
+export interface SecretSignature {
+  pattern: RegExp;
+  label: string;
+  description: string;
+}
+
+export const SECRET_SIGNATURES: SecretSignature[] = [
+  {
+    pattern: /sk-ant-api\d{2}-[A-Za-z0-9_-]{20,}/,
+    label: 'anthropic-api-key',
+    description: 'Anthropic API key',
+  },
+  {
+    pattern: /sk-[A-Za-z0-9]{48,}/,
+    label: 'openai-api-key',
+    description: 'OpenAI API key',
+  },
+  {
+    pattern: /ghp_[A-Za-z0-9]{36,}/,
+    label: 'github-pat',
+    description: 'GitHub personal access token',
+  },
+  {
+    pattern: /gho_[A-Za-z0-9]{36,}/,
+    label: 'github-oauth',
+    description: 'GitHub OAuth access token',
+  },
+  {
+    pattern: /github_pat_[A-Za-z0-9_]{20,}/,
+    label: 'github-fine-grained-pat',
+    description: 'GitHub fine-grained personal access token',
+  },
+  {
+    pattern: /xoxb-[0-9]{10,}-[0-9]{10,}-[A-Za-z0-9]{24,}/,
+    label: 'slack-bot-token',
+    description: 'Slack bot token',
+  },
+  {
+    pattern: /xoxp-[0-9]{10,}-[0-9]{10,}-[A-Za-z0-9]{24,}/,
+    label: 'slack-user-token',
+    description: 'Slack user token',
+  },
+  {
+    pattern: /eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}/,
+    label: 'supabase-jwt',
+    description: 'Supabase JWT (anon or service_role key)',
+  },
+  {
+    pattern: /AKIA[0-9A-Z]{16}/,
+    label: 'aws-access-key',
+    description: 'AWS access key ID',
+  },
+  {
+    pattern: /npm_[A-Za-z0-9]{36,}/,
+    label: 'npm-token',
+    description: 'npm access token',
+  },
+  {
+    pattern: /sk_live_[A-Za-z0-9]{24,}/,
+    label: 'stripe-secret-key',
+    description: 'Stripe secret key',
+  },
+  {
+    pattern: /sq0csp-[A-Za-z0-9_-]{43}/,
+    label: 'square-oauth-secret',
+    description: 'Square OAuth secret',
+  },
+  {
+    pattern: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/,
+    label: 'sendgrid-api-key',
+    description: 'SendGrid API key',
+  },
+  {
+    pattern: /-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----/,
+    label: 'private-key',
+    description: 'Private key file',
+  },
+];

package/src/scanners/secrets-exposure/rules/entropy-check.rule.ts

@@ -0,0 +1,79 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import type { Rule, ScanContext } from '../../../types/index.js';
+
+const CODE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.json', '.yaml', '.yml',
+  '.toml', '.cfg', '.ini', '.env',
+]);
+
+function isTargetFile(file: string): boolean {
+  const dot = file.lastIndexOf('.');
+  if (dot === -1) return basename(file).startsWith('.env');
+  return CODE_EXTENSIONS.has(file.slice(dot).toLowerCase());
+}
+
+function shannonEntropy(s: string): number {
+  if (s.length === 0) return 0;
+  const freq = new Map<string, number>();
+  for (const ch of s) {
+    freq.set(ch, (freq.get(ch) ?? 0) + 1);
+  }
+  let entropy = 0;
+  for (const count of freq.values()) {
+    const p = count / s.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+// Match assignment-like patterns: KEY=value, "key": "value", key: value
+const ASSIGNMENT_PATTERN = /(?:['"]?(?:key|token|secret|password|api_key|apikey|auth|credential|private)['"_\s]*[:=]\s*['"]?)([A-Za-z0-9+/=_-]{16,})/gi;
+
+const ENTROPY_THRESHOLD = 4.5;
+const MIN_LENGTH = 16;
+
+export const entropyCheckRule: Rule = {
+  id: 'entropy-check',
+  name: 'High Entropy String Detection',
+  description: 'Flags high-entropy strings in assignment contexts that may be hardcoded secrets',
+
+  async run(ctx: ScanContext): Promise<void> {
+    for (const file of ctx.files) {
+      if (!isTargetFile(file)) continue;
+
+      let content: string;
+      try {
+        content = await readFile(file, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*#/.test(line) || /^\s*\/\//.test(line)) continue;
+
+        ASSIGNMENT_PATTERN.lastIndex = 0;
+        let match: RegExpExecArray | null;
+        while ((match = ASSIGNMENT_PATTERN.exec(line)) !== null) {
+          const value = match[1];
+          if (value.length < MIN_LENGTH) continue;
+
+          const entropy = shannonEntropy(value);
+          if (entropy >= ENTROPY_THRESHOLD) {
+            ctx.addFinding({
+              rule: 'entropy-check',
+              severity: 'high',
+              message: `High-entropy string (${entropy.toFixed(2)} bits) in secret-like assignment`,
+              location: { file, line: i + 1 },
+              evidence: value.slice(0, 8) + '...[REDACTED]',
+              suggestion: 'This looks like a hardcoded credential. Move it to an environment variable.',
+              metadata: { entropy },
+            });
+          }
+        }
+      }
+    }
+  },
+};

package/src/scanners/secrets-exposure/rules/known-patterns.rule.ts

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import type { Rule, ScanContext } from '../../../types/index.js';
+import { SECRET_SIGNATURES } from '../patterns/secret-signatures.js';
+
+const SKIP_FILES = new Set([
+  'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+  '.gitignore', '.dockerignore',
+]);
+
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2',
+  '.ttf', '.eot', '.zip', '.tar', '.gz', '.pdf',
+]);
+
+function shouldSkip(file: string): boolean {
+  const name = basename(file);
+  if (SKIP_FILES.has(name)) return true;
+  const dot = file.lastIndexOf('.');
+  if (dot !== -1 && BINARY_EXTENSIONS.has(file.slice(dot).toLowerCase())) return true;
+  return false;
+}
+
+export const knownPatternsRule: Rule = {
+  id: 'known-patterns',
+  name: 'Known Secret Patterns',
+  description: 'Matches known API key and credential patterns in source files',
+
+  async run(ctx: ScanContext): Promise<void> {
+    for (const file of ctx.files) {
+      if (shouldSkip(file)) continue;
+
+      let content: string;
+      try {
+        content = await readFile(file, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+
+        // Skip lines that are env template placeholders
+        if (/^\s*#/.test(line) || /=\s*$/.test(line) || /YOUR_.*_HERE/.test(line)) {
+          continue;
+        }
+
+        for (const sig of SECRET_SIGNATURES) {
+          if (sig.pattern.test(line)) {
+            ctx.addFinding({
+              rule: 'known-patterns',
+              severity: 'critical',
+              message: `${sig.description} found in source code`,
+              location: { file, line: i + 1 },
+              evidence: line.trim().slice(0, 40) + '...[REDACTED]',
+              suggestion: `Move this ${sig.label} to an environment variable. Never commit secrets to source control.`,
+            });
+          }
+        }
+      }
+    }
+  },
+};

package/src/scanners/secrets-exposure/rules/response-echo.rule.ts

@@ -0,0 +1,70 @@
+import { readFile } from 'node:fs/promises';
+import type { Rule, ScanContext } from '../../../types/index.js';
+
+const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+
+function isCodeFile(file: string): boolean {
+  const dot = file.lastIndexOf('.');
+  return dot !== -1 && CODE_EXTENSIONS.has(file.slice(dot).toLowerCase());
+}
+
+// Patterns where env vars are passed into responses, logs, or error messages
+const ECHO_PATTERNS = [
+  {
+    pattern: /(?:res\.(?:json|send|write)|console\.(?:log|error|warn))\s*\([^)]*process\.env\.[A-Z_]*(?:KEY|SECRET|TOKEN|PASSWORD)/g,
+    label: 'env-var-in-response',
+    description: 'Environment variable containing a secret echoed in response or log',
+  },
+  {
+    pattern: /(?:JSON\.stringify|toString)\s*\([^)]*process\.env\b/g,
+    label: 'env-serialization',
+    description: 'process.env serialized — may leak all environment variables',
+  },
+  {
+    pattern: /(?:res\.(?:json|send))\s*\(\s*\{\s*\.\.\.(?:process\.env|req\.)/g,
+    label: 'spread-leak',
+    description: 'Object spread may leak sensitive fields into response',
+  },
+  {
+    pattern: /error\.stack|err\.stack/g,
+    label: 'stack-trace-exposure',
+    description: 'Stack trace exposed — may reveal file paths and internal structure',
+  },
+];
+
+export const responseEchoRule: Rule = {
+  id: 'response-echo',
+  name: 'Response Echo Detection',
+  description: 'Detects secrets or sensitive data being echoed in HTTP responses or logs',
+
+  async run(ctx: ScanContext): Promise<void> {
+    const codeFiles = ctx.files.filter(isCodeFile);
+
+    for (const file of codeFiles) {
+      let content: string;
+      try {
+        content = await readFile(file, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const { pattern, label, description } of ECHO_PATTERNS) {
+          pattern.lastIndex = 0;
+          if (pattern.test(line)) {
+            ctx.addFinding({
+              rule: 'response-echo',
+              severity: label === 'stack-trace-exposure' ? 'medium' : 'high',
+              message: description,
+              location: { file, line: i + 1 },
+              evidence: line.trim().slice(0, 200),
+              suggestion: 'Never echo secrets or full env objects in responses. Sanitize output.',
+            });
+          }
+        }
+      }
+    }
+  },
+};

package/src/scanners/secrets-exposure/scanner.ts

@@ -0,0 +1,25 @@
+import type { Scanner, ScanContext, Rule } from '../../types/index.js';
+import { entropyCheckRule } from './rules/entropy-check.rule.js';
+import { knownPatternsRule } from './rules/known-patterns.rule.js';
+import { responseEchoRule } from './rules/response-echo.rule.js';
+
+const rules: Rule[] = [
+  knownPatternsRule,
+  entropyCheckRule,
+  responseEchoRule,
+];
+
+export const secretsExposureScanner: Scanner = {
+  id: 'secrets-exposure',
+  name: 'Secrets Exposure',
+  description: 'Detects hardcoded secrets, high-entropy strings, and response echo vulnerabilities',
+  rules,
+
+  async scan(ctx: ScanContext): Promise<void> {
+    for (const rule of rules) {
+      const ruleConfig = ctx.scannerConfig.rules?.[rule.id];
+      if (ruleConfig?.enabled === false) continue;
+      await rule.run(ctx);
+    }
+  },
+};

package/src/types/config.types.ts

@@ -0,0 +1,40 @@
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+
+export type ScannerId =
+  | 'ai-tool-integrity'
+  | 'secrets-exposure'
+  | 'dependency-integrity'
+  | 'runtime-monitor';
+
+export interface RuleConfig {
+  enabled: boolean;
+  severity?: Severity;
+  options?: Record<string, unknown>;
+}
+
+export interface ScannerConfig {
+  enabled: boolean;
+  rules?: Record<string, RuleConfig>;
+}
+
+export interface WatchmanConfig {
+  projectRoot: string;
+  scanners: Partial<Record<ScannerId, ScannerConfig>>;
+  include?: string[];
+  exclude?: string[];
+  failOn?: Severity;
+  quiet?: boolean;
+  maxFindings?: number;
+}
+
+export const DEFAULT_CONFIG: Omit<WatchmanConfig, 'projectRoot'> = {
+  scanners: {
+    'ai-tool-integrity': { enabled: true },
+    'secrets-exposure': { enabled: true },
+    'dependency-integrity': { enabled: true },
+    'runtime-monitor': { enabled: false },
+  },
+  exclude: ['node_modules', '.git', 'dist', 'build', '.next'],
+  failOn: 'high',
+  quiet: false,
+};

package/src/types/context.types.ts

@@ -0,0 +1,25 @@
+import type { WatchmanConfig, ScannerConfig, ScannerId } from './config.types.js';
+import type { Finding } from './finding.types.js';
+
+export interface ScanContext {
+  config: WatchmanConfig;
+  scannerId: ScannerId;
+  scannerConfig: ScannerConfig;
+  files: string[];
+  addFinding: (finding: Omit<Finding, 'id' | 'scanner'>) => void;
+}
+
+export interface Rule {
+  id: string;
+  name: string;
+  description: string;
+  run: (ctx: ScanContext) => Promise<void>;
+}
+
+export interface Scanner {
+  id: ScannerId;
+  name: string;
+  description: string;
+  rules: Rule[];
+  scan: (ctx: ScanContext) => Promise<void>;
+}

package/src/types/finding.types.ts

@@ -0,0 +1,36 @@
+import type { Severity, ScannerId } from './config.types.js';
+
+export interface SourceLocation {
+  file: string;
+  line?: number;
+  column?: number;
+}
+
+export interface Finding {
+  id: string;
+  scanner: ScannerId;
+  rule: string;
+  severity: Severity;
+  message: string;
+  location?: SourceLocation;
+  evidence?: string;
+  suggestion?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ScanResult {
+  scanner: ScannerId;
+  findings: Finding[];
+  duration: number;
+  filesScanned: number;
+}
+
+export interface WatchmanReport {
+  timestamp: string;
+  projectRoot: string;
+  results: ScanResult[];
+  totalFindings: number;
+  maxSeverity: Severity | null;
+  passed: boolean;
+  duration: number;
+}

package/src/types/index.ts

@@ -0,0 +1,21 @@
+export type {
+  Severity,
+  ScannerId,
+  RuleConfig,
+  ScannerConfig,
+  WatchmanConfig,
+} from './config.types.js';
+export { DEFAULT_CONFIG } from './config.types.js';
+
+export type {
+  SourceLocation,
+  Finding,
+  ScanResult,
+  WatchmanReport,
+} from './finding.types.js';
+
+export type {
+  ScanContext,
+  Rule,
+  Scanner,
+} from './context.types.js';

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/watchman.config.ts

@@ -0,0 +1,16 @@
+import type { WatchmanConfig } from './src/types/config.types.js';
+
+const config: WatchmanConfig = {
+  projectRoot: process.cwd(),
+  scanners: {
+    'ai-tool-integrity': { enabled: true },
+    'secrets-exposure': { enabled: true },
+    'dependency-integrity': { enabled: true },
+    'runtime-monitor': { enabled: false },
+  },
+  exclude: ['node_modules', '.git', 'dist', 'build', '.next'],
+  failOn: 'high',
+  quiet: false,
+};
+
+export default config;