openpen 0.2.0

package/dist/cli.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * openpen - Open source API fuzzing and penetration testing CLI
+ */
+import { Command } from 'commander';
+import { setVerbose, info, error } from './utils/logger.js';
+import { loadTarget } from './spec/parser.js';
+import { FuzzEngine } from './fuzzer/engine.js';
+import { getAllChecks, getChecksByIds, listChecks } from './checks/index.js';
+import { getAllWsChecks, getWsChecksByIds, listWsChecks } from './ws/checks.js';
+import { reportTerminal, reportJson } from './reporter/index.js';
+const program = new Command();
+program
+    .name('openpen')
+    .description('Open source CLI for API fuzzing and penetration testing')
+    .version('0.1.0');
+// scan command
+program
+    .command('scan')
+    .description('Run OWASP security checks against an API')
+    .argument('<target>', 'Base URL of the API')
+    .option('--spec <path>', 'Path or URL to OpenAPI/Swagger spec')
+    .option('--checks <list>', 'Comma-separated check IDs to run')
+    .option('--exclude-checks <list>', 'Checks to skip')
+    .option('--auth-header <header>', 'Auth header (e.g. "Authorization: Bearer tok")', collect, [])
+    .option('--auth-token <token>', 'Bearer token shorthand')
+    .option('--method <methods>', 'HTTP methods to test (comma-separated)')
+    .option('--paths <paths>', 'Comma-separated paths to test (manual mode)')
+    .option('--depth <level>', 'Payload volume: shallow, normal, deep', 'normal')
+    .option('--output <file>', 'Write report to file')
+    .option('--format <fmt>', 'Output format: terminal, json', 'terminal')
+    .option('--timeout <ms>', 'Per-request timeout in ms', '10000')
+    .option('--concurrency <n>', 'Max concurrent requests', '10')
+    .option('--rate-limit <n>', 'Max requests per second', '50')
+    .option('--verbose', 'Show individual request details')
+    .option('--no-color', 'Disable colored output')
+    .action(async (targetUrl, opts) => {
+    setVerbose(opts.verbose || false);
+    const auth = parseAuth(opts.authHeader, opts.authToken);
+    const target = await loadTarget(targetUrl, {
+        specPath: opts.spec,
+        methods: opts.method?.split(','),
+        paths: opts.paths?.split(','),
+        auth,
+    });
+    if (target.endpoints.length === 0) {
+        error('No endpoints found. Provide --spec or --paths.');
+        process.exit(1);
+    }
+    info(`\n OPENPEN v0.1.0 -- API Security Scanner\n`);
+    info(` Target:     ${targetUrl}`);
+    info(` Endpoints:  ${target.endpoints.length}`);
+    info(` Depth:      ${opts.depth}`);
+    const config = {
+        depth: opts.depth,
+        checks: opts.checks ? opts.checks.split(',') : [],
+        excludeChecks: opts.excludeChecks ? opts.excludeChecks.split(',') : [],
+        timeout: parseInt(opts.timeout),
+        concurrency: parseInt(opts.concurrency),
+        rateLimit: parseInt(opts.rateLimit),
+        verbose: opts.verbose || false,
+        noColor: !opts.color,
+    };
+    const checks = config.checks.length > 0
+        ? getChecksByIds(config.checks)
+        : getAllChecks().filter(c => !config.excludeChecks.includes(c.id));
+    info(` Checks:     ${checks.length} modules\n`);
+    const startedAt = new Date();
+    let totalRequests = 0;
+    const findings = [];
+    for (const check of checks) {
+        info(` Running: ${check.name}...`);
+        const result = await check.run(target, config);
+        findings.push(...result.findings);
+        totalRequests += result.requestCount;
+    }
+    const completedAt = new Date();
+    const report = {
+        target: targetUrl,
+        startedAt: startedAt.toISOString(),
+        completedAt: completedAt.toISOString(),
+        duration: completedAt.getTime() - startedAt.getTime(),
+        totalRequests,
+        findings,
+        summary: {
+            critical: findings.filter(f => f.severity === 'critical').length,
+            high: findings.filter(f => f.severity === 'high').length,
+            medium: findings.filter(f => f.severity === 'medium').length,
+            low: findings.filter(f => f.severity === 'low').length,
+            info: findings.filter(f => f.severity === 'info').length,
+        },
+        checksRun: checks.map(c => c.id),
+    };
+    if (opts.format === 'json') {
+        reportJson(report, opts.output);
+    }
+    else {
+        reportTerminal(report, !opts.color);
+    }
+});
+// fuzz command
+program
+    .command('fuzz')
+    .description('Fuzz API endpoints with mutated payloads')
+    .argument('<target>', 'URL to fuzz')
+    .option('--method <method>', 'HTTP method', 'GET')
+    .option('--body <json>', 'Request body (use FUZZ as placeholder)')
+    .option('--headers <json>', 'Additional headers as JSON')
+    .option('--fuzz-params <list>', 'Parameters to fuzz (comma-separated)')
+    .option('--wordlist <name>', 'Wordlist: sqli, xss, path-traversal, ssrf, all', 'all')
+    .option('--detect <methods>', 'Anomaly detection: status,length,time,content', 'status,length,time,content')
+    .option('--baseline', 'Send clean request first for comparison')
+    .option('--auth-header <header>', 'Auth header', collect, [])
+    .option('--auth-token <token>', 'Bearer token shorthand')
+    .option('--timeout <ms>', 'Per-request timeout', '10000')
+    .option('--concurrency <n>', 'Max concurrent requests', '10')
+    .option('--rate-limit <n>', 'Max requests per second', '50')
+    .option('--output <file>', 'Write results to file')
+    .option('--verbose', 'Show each request/response')
+    .action(async (targetUrl, opts) => {
+    setVerbose(opts.verbose || false);
+    const auth = parseAuth(opts.authHeader, opts.authToken);
+    const engine = new FuzzEngine({
+        timeout: parseInt(opts.timeout),
+        concurrency: parseInt(opts.concurrency),
+        rateLimit: parseInt(opts.rateLimit),
+        verbose: opts.verbose || false,
+    });
+    info(`\n OPENPEN v0.1.0 -- Fuzzer\n`);
+    info(` Target: ${targetUrl}`);
+    info(` Method: ${opts.method}`);
+    info(` Wordlist: ${opts.wordlist}\n`);
+    const results = await engine.fuzz({
+        url: targetUrl,
+        method: opts.method,
+        body: opts.body,
+        headers: {
+            ...(opts.headers ? JSON.parse(opts.headers) : {}),
+            ...(auth?.headers || {}),
+        },
+        fuzzParams: opts.fuzzParams?.split(',') || [],
+        wordlist: opts.wordlist,
+        detect: opts.detect.split(','),
+        baseline: opts.baseline || false,
+    });
+    const anomalies = results.filter(r => r.anomalies.length > 0);
+    info(`\n Results: ${anomalies.length} anomalies from ${results.length} requests\n`);
+    for (const r of anomalies) {
+        info(`  [${r.anomalies.join(',')}] ${r.payload} -> ${r.response.statusCode} (${r.response.responseTime}ms)`);
+    }
+    if (opts.output) {
+        const { writeFileSync } = await import('fs');
+        writeFileSync(opts.output, JSON.stringify(results, null, 2));
+        info(`\n Report written to ${opts.output}`);
+    }
+});
+// info command
+program
+    .command('info')
+    .description('Reconnaissance - fingerprint an API')
+    .argument('<target>', 'Base URL of the API')
+    .option('--spec <path>', 'Path or URL to OpenAPI/Swagger spec')
+    .option('--auth-header <header>', 'Auth header', collect, [])
+    .option('--auth-token <token>', 'Bearer token shorthand')
+    .action(async (targetUrl, opts) => {
+    const auth = parseAuth(opts.authHeader, opts.authToken);
+    const target = await loadTarget(targetUrl, {
+        specPath: opts.spec,
+        auth,
+    });
+    info(`\n OPENPEN v0.1.0 -- API Recon\n`);
+    info(` Target: ${targetUrl}`);
+    info(` Endpoints: ${target.endpoints.length}\n`);
+    for (const ep of target.endpoints) {
+        const params = ep.parameters.map(p => `${p.name}(${p.in})`).join(', ');
+        info(`  ${ep.method.padEnd(7)} ${ep.path}${params ? '  [' + params + ']' : ''}`);
+    }
+    // Fingerprint
+    try {
+        const res = await fetch(targetUrl, { signal: AbortSignal.timeout(5000) });
+        info(`\n Server Headers:`);
+        for (const [k, v] of res.headers) {
+            if (['server', 'x-powered-by', 'x-frame-options', 'x-content-type-options',
+                'strict-transport-security', 'content-security-policy',
+                'access-control-allow-origin'].includes(k.toLowerCase())) {
+                info(`  ${k}: ${v}`);
+            }
+        }
+    }
+    catch {
+        info(`\n Could not reach ${targetUrl} for fingerprinting`);
+    }
+});
+// ws-test command
+program
+    .command('ws-test')
+    .description('Run security checks against a WebSocket endpoint')
+    .argument('<target>', 'WebSocket URL (ws:// or wss://)')
+    .option('--checks <list>', 'Comma-separated check IDs to run')
+    .option('--exclude-checks <list>', 'Checks to skip')
+    .option('--timeout <ms>', 'Connection timeout in ms', '5000')
+    .option('--output <file>', 'Write report to file')
+    .option('--format <fmt>', 'Output format: terminal, json', 'terminal')
+    .option('--verbose', 'Show detailed test output')
+    .action(async (targetUrl, opts) => {
+    setVerbose(opts.verbose || false);
+    // Validate URL scheme
+    if (!targetUrl.startsWith('ws://') && !targetUrl.startsWith('wss://')) {
+        // Auto-upgrade http(s) to ws(s)
+        targetUrl = targetUrl.replace(/^https:/, 'wss:').replace(/^http:/, 'ws:');
+        if (!targetUrl.startsWith('ws://') && !targetUrl.startsWith('wss://')) {
+            targetUrl = `wss://${targetUrl}`;
+        }
+    }
+    const timeout = parseInt(opts.timeout);
+    const allChecks = opts.checks
+        ? getWsChecksByIds(opts.checks.split(','))
+        : getAllWsChecks().filter(c => !(opts.excludeChecks || '').split(',').includes(c.info.id));
+    info(`\n OPENPEN v0.1.0 -- WebSocket Security Tester\n`);
+    info(` Target:  ${targetUrl}`);
+    info(` Checks:  ${allChecks.length} modules\n`);
+    const startedAt = new Date();
+    const results = [];
+    for (const check of allChecks) {
+        info(` Running: ${check.info.name}...`);
+        const result = await check.run(targetUrl, timeout);
+        results.push(result);
+        const icon = result.status === 'pass' ? 'OK' :
+            result.status === 'fail' ? 'FAIL' :
+                result.status === 'warn' ? 'WARN' : 'ERR';
+        const sev = result.status === 'pass' ? '' : ` [${result.severity.toUpperCase()}]`;
+        info(`   ${icon}${sev} ${result.description}`);
+    }
+    const completedAt = new Date();
+    const report = {
+        target: targetUrl,
+        startedAt: startedAt.toISOString(),
+        completedAt: completedAt.toISOString(),
+        duration: completedAt.getTime() - startedAt.getTime(),
+        results,
+        summary: {
+            pass: results.filter(r => r.status === 'pass').length,
+            fail: results.filter(r => r.status === 'fail').length,
+            warn: results.filter(r => r.status === 'warn').length,
+            error: results.filter(r => r.status === 'error').length,
+        },
+    };
+    info(`\n Summary: ${report.summary.pass} pass, ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.error} error`);
+    info(` Duration: ${report.duration}ms\n`);
+    if (opts.format === 'json' || opts.output) {
+        const json = JSON.stringify(report, null, 2);
+        if (opts.output) {
+            const { writeFileSync } = await import('fs');
+            writeFileSync(opts.output, json);
+            info(` Report written to ${opts.output}\n`);
+        }
+        else {
+            console.log(json);
+        }
+    }
+});
+// list-checks command
+program
+    .command('list-checks')
+    .description('List available security check modules')
+    .action(() => {
+    info(`\n OPENPEN v0.1.0 -- Available Checks\n`);
+    info(` HTTP API Checks:`);
+    const checks = listChecks();
+    for (const c of checks) {
+        info(`  ${c.id.padEnd(20)} ${c.owaspCategory.padEnd(25)} ${c.name}`);
+    }
+    info(`\n WebSocket Checks:`);
+    const wsChecks = listWsChecks();
+    for (const c of wsChecks) {
+        info(`  ${c.id.padEnd(20)} ${''.padEnd(25)} ${c.name}`);
+    }
+    info('');
+});
+// Helpers
+function collect(val, prev) {
+    prev.push(val);
+    return prev;
+}
+function parseAuth(headers, token) {
+    const result = {};
+    for (const h of headers) {
+        const idx = h.indexOf(':');
+        if (idx > 0) {
+            result[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
+        }
+    }
+    if (token) {
+        result['Authorization'] = `Bearer ${token}`;
+    }
+    if (Object.keys(result).length === 0)
+        return undefined;
+    return { headers: result };
+}
+program.parse();

package/dist/fuzzer/engine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Core fuzzing orchestrator
+ */
+import type { FuzzResult } from '../types.js';
+export interface FuzzEngineConfig {
+    timeout: number;
+    concurrency: number;
+    rateLimit: number;
+    verbose: boolean;
+}
+export interface FuzzRequest {
+    url: string;
+    method: string;
+    body?: string;
+    headers: Record<string, string>;
+    fuzzParams: string[];
+    wordlist: string;
+    detect: string[];
+    baseline: boolean;
+}
+export declare class FuzzEngine {
+    private semaphore;
+    private rateLimiter;
+    private config;
+    constructor(config: FuzzEngineConfig);
+    fuzz(req: FuzzRequest): Promise<FuzzResult[]>;
+}

package/dist/fuzzer/engine.js

@@ -0,0 +1,126 @@
+/**
+ * Core fuzzing orchestrator
+ */
+import { sendRequest, Semaphore, RateLimiter } from '../utils/http.js';
+import { getPayloads } from './payloads.js';
+import { info, verbose } from '../utils/logger.js';
+export class FuzzEngine {
+    semaphore;
+    rateLimiter;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.semaphore = new Semaphore(config.concurrency);
+        this.rateLimiter = new RateLimiter(config.rateLimit);
+    }
+    async fuzz(req) {
+        const payloads = getPayloads(req.wordlist);
+        info(` Payloads:  ${payloads.length}`);
+        // Get baseline if requested
+        let baselineResponse;
+        if (req.baseline) {
+            verbose('  Getting baseline response...');
+            const cleanUrl = req.url.replace(/FUZZ/g, 'test');
+            const cleanBody = req.body?.replace(/FUZZ/g, 'test');
+            try {
+                const res = await sendRequest({
+                    url: cleanUrl,
+                    method: req.method,
+                    headers: req.headers,
+                    body: cleanBody,
+                    timeout: this.config.timeout,
+                });
+                baselineResponse = res.response;
+                verbose(`  Baseline: ${baselineResponse.statusCode} (${baselineResponse.responseTime}ms, ${baselineResponse.bodySnippet.length} bytes)`);
+            }
+            catch {
+                verbose('  Baseline request failed, continuing without');
+            }
+        }
+        const results = [];
+        const detectors = new Set(req.detect);
+        const tasks = payloads.map(payload => async () => {
+            await this.semaphore.acquire();
+            try {
+                await this.rateLimiter.wait();
+                const fuzzedUrl = req.url.replace(/FUZZ/g, encodeURIComponent(payload));
+                const fuzzedBody = req.body?.replace(/FUZZ/g, payload);
+                const res = await sendRequest({
+                    url: fuzzedUrl,
+                    method: req.method,
+                    headers: req.headers,
+                    body: fuzzedBody,
+                    timeout: this.config.timeout,
+                });
+                const anomalies = detectAnomalies(res.response, baselineResponse, payload, detectors);
+                results.push({
+                    payload,
+                    request: res.request,
+                    response: res.response,
+                    anomalies,
+                    baseline: baselineResponse,
+                });
+            }
+            catch (err) {
+                verbose(`  Error fuzzing with payload "${payload.slice(0, 30)}": ${err}`);
+            }
+            finally {
+                this.semaphore.release();
+            }
+        });
+        // Execute all fuzz tasks
+        await Promise.all(tasks.map(t => t()));
+        return results;
+    }
+}
+function detectAnomalies(response, baseline, payload, detectors) {
+    const anomalies = [];
+    // Status code change
+    if (detectors.has('status') && baseline) {
+        if (response.statusCode !== baseline.statusCode) {
+            // 500 errors are especially interesting
+            if (response.statusCode >= 500) {
+                anomalies.push('status_change');
+            }
+            else if (Math.floor(response.statusCode / 100) !== Math.floor(baseline.statusCode / 100)) {
+                anomalies.push('status_change');
+            }
+        }
+    }
+    // Response length anomaly
+    if (detectors.has('length') && baseline) {
+        const baseLen = baseline.bodySnippet.length;
+        const resLen = response.bodySnippet.length;
+        if (baseLen > 0) {
+            const ratio = Math.abs(resLen - baseLen) / baseLen;
+            if (ratio > 0.5) {
+                anomalies.push('length_anomaly');
+            }
+        }
+    }
+    // Timing anomaly (possible time-based injection)
+    if (detectors.has('time') && baseline) {
+        if (response.responseTime > baseline.responseTime * 3 && response.responseTime > 3000) {
+            anomalies.push('time_anomaly');
+        }
+    }
+    // Error string detection
+    if (detectors.has('content')) {
+        const body = response.bodySnippet.toLowerCase();
+        const errorPatterns = [
+            'sql syntax', 'mysql', 'postgresql', 'sqlite', 'ora-',
+            'syntax error', 'uncaught exception', 'stack trace',
+            'internal server error', 'fatal error',
+            'root:', '/etc/passwd', '/bin/sh',
+            'access denied', 'permission denied',
+        ];
+        if (errorPatterns.some(p => body.includes(p))) {
+            anomalies.push('error_string');
+        }
+        // Check for payload reflection (potential XSS)
+        if (response.bodySnippet.includes(payload)) {
+            anomalies.push('reflection');
+        }
+    }
+    return anomalies;
+}

package/dist/fuzzer/mutator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Payload mutation strategies - encoding, case variation, null bytes
+ */
+export type MutationStrategy = 'url-encode' | 'double-encode' | 'unicode' | 'case-swap' | 'null-byte' | 'concat';
+/**
+ * Apply a set of mutations to a payload, returning all variants
+ */
+export declare function mutatePayload(payload: string, strategies?: MutationStrategy[]): string[];

package/dist/fuzzer/mutator.js

@@ -0,0 +1,54 @@
+/**
+ * Payload mutation strategies - encoding, case variation, null bytes
+ */
+/**
+ * Apply a set of mutations to a payload, returning all variants
+ */
+export function mutatePayload(payload, strategies) {
+    const strats = strategies || ['url-encode', 'double-encode', 'case-swap', 'null-byte'];
+    const results = [payload]; // always include original
+    for (const s of strats) {
+        const mutated = applyMutation(payload, s);
+        if (mutated !== payload) {
+            results.push(mutated);
+        }
+    }
+    return results;
+}
+function applyMutation(payload, strategy) {
+    switch (strategy) {
+        case 'url-encode':
+            return urlEncode(payload);
+        case 'double-encode':
+            return urlEncode(urlEncode(payload));
+        case 'unicode':
+            return unicodeEscape(payload);
+        case 'case-swap':
+            return caseSwap(payload);
+        case 'null-byte':
+            return payload + '%00';
+        case 'concat':
+            return concatSplit(payload);
+    }
+}
+function urlEncode(s) {
+    return encodeURIComponent(s);
+}
+function unicodeEscape(s) {
+    return s.replace(/[<>'"/\\]/g, ch => {
+        const code = ch.charCodeAt(0);
+        return `\\u${code.toString(16).padStart(4, '0')}`;
+    });
+}
+function caseSwap(s) {
+    return s.replace(/[a-zA-Z]/g, ch => {
+        return ch === ch.toLowerCase() ? ch.toUpperCase() : ch.toLowerCase();
+    });
+}
+function concatSplit(s) {
+    // Split strings at midpoint with concat operator
+    if (s.length < 4)
+        return s;
+    const mid = Math.floor(s.length / 2);
+    return s.slice(0, mid) + "'+'" + s.slice(mid);
+}

package/dist/fuzzer/payloads.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Built-in payload dictionaries for fuzzing
+ */
+export declare const SQLI_PAYLOADS: string[];
+export declare const XSS_PAYLOADS: string[];
+export declare const PATH_TRAVERSAL_PAYLOADS: string[];
+export declare const SSRF_PAYLOADS: string[];
+export declare const NOSQL_PAYLOADS: string[];
+export declare const COMMAND_INJECTION_PAYLOADS: string[];
+export declare const PROMPT_INJECTION_PAYLOADS: string[];
+export declare const LLM_LEAK_PAYLOADS: string[];
+export type WordlistName = 'sqli' | 'xss' | 'path-traversal' | 'ssrf' | 'nosql' | 'command-injection' | 'prompt-injection' | 'llm-leak' | 'all';
+export declare function getPayloads(name: WordlistName): string[];