@apiposture/cli 1.0.1

package/.apiposture.json.example

@@ -0,0 +1,56 @@
+{
+  "rules": {
+    "AP001": {
+      "enabled": true
+    },
+    "AP002": {
+      "enabled": true
+    },
+    "AP003": {
+      "enabled": true
+    },
+    "AP004": {
+      "enabled": true
+    },
+    "AP005": {
+      "enabled": true,
+      "options": {
+        "maxRoles": 3
+      }
+    },
+    "AP006": {
+      "enabled": true
+    },
+    "AP007": {
+      "enabled": true
+    },
+    "AP008": {
+      "enabled": true
+    }
+  },
+  "suppressions": [
+    {
+      "ruleId": "AP001",
+      "route": "/api/health",
+      "reason": "Health check endpoint is intentionally public"
+    },
+    {
+      "ruleId": "AP002",
+      "routePattern": "/api/public/*",
+      "reason": "Public API routes are intentionally unauthenticated"
+    }
+  ],
+  "output": {
+    "format": "terminal",
+    "noColor": false,
+    "noIcons": false
+  },
+  "scan": {
+    "excludePatterns": [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/*.test.ts",
+      "**/*.spec.ts"
+    ]
+  }
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -0,0 +1,42 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint --if-present
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Test CLI execution
+        run: |
+          node dist/index.js --version
+          node dist/index.js scan samples/express-sample -o json > /dev/null

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlagoCuljak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# ApiPosture CLI for Node.js
+
+Static source-code analysis CLI for Node.js API frameworks to identify authorization misconfigurations and security risks.
+
+## Features
+
+- **Multi-Framework Support**: Express.js, NestJS, Fastify, and Koa
+- **8 Security Rules**: Covering exposure, consistency, privilege, and surface area risks
+- **Multiple Output Formats**: Terminal, JSON, and Markdown
+- **Configurable**: Rule customization and suppression support
+- **CI/CD Ready**: Exit codes for pipeline integration
+
+## Installation
+
+```bash
+npm install -g @apiposture/cli
+```
+
+Or use with npx:
+
+```bash
+npx @apiposture/cli scan .
+```
+
+## Quick Start
+
+```bash
+# Scan current directory
+apiposture scan
+
+# Scan specific path
+apiposture scan ./src
+
+# Output as JSON
+apiposture scan -o json
+
+# Fail CI if critical findings
+apiposture scan --fail-on critical
+```
+
+## Security Rules
+
+| Rule | Name | Severity | Description |
+|------|------|----------|-------------|
+| AP001 | Public without explicit intent | High | Endpoint is public without @Public or allowAnonymous marker |
+| AP002 | AllowAnonymous on write | High | Write operation explicitly marked as public |
+| AP003 | Controller/action conflict | Medium | Method @Public overrides class-level guards (NestJS) |
+| AP004 | Missing auth on writes | Critical | Unprotected write endpoint |
+| AP005 | Excessive role access | Low | Endpoint allows >3 roles |
+| AP006 | Weak role naming | Low | Generic role names like "admin", "user" |
+| AP007 | Sensitive route keywords | Medium | Public route contains admin/debug/internal |
+| AP008 | Unprotected endpoint | High | No middleware chain at all |
+
+## CLI Options
+
+```bash
+apiposture scan [path]
+
+Options:
+  -o, --output <format>        Output format: terminal, json, markdown (default: terminal)
+  -f, --output-file <path>     Write output to file
+  -c, --config <path>          Config file path (.apiposture.json)
+  --severity <level>           Min severity: info, low, medium, high, critical
+  --fail-on <level>            Exit code 1 if findings at this level
+  --sort-by <field>            Sort by: severity, route, method, classification
+  --sort-dir <dir>             Sort direction: asc, desc
+  --classification <types>     Filter: public, authenticated, role-restricted, policy-restricted
+  --method <methods>           Filter: GET, POST, PUT, DELETE, PATCH
+  --route-contains <str>       Filter routes containing string
+  --api-style <styles>         Filter: express, nestjs, fastify, koa
+  --rule <rules>               Filter by rule ID (comma-separated)
+  --no-color                   Disable colors
+  --no-icons                   Disable icons
+
+License Commands:
+  apiposture license activate <key>    Activate a license
+  apiposture license deactivate        Deactivate current license
+  apiposture license status            Show license status
+```
+
+## Configuration
+
+Create `.apiposture.json` in your project root:
+
+```json
+{
+  "rules": {
+    "AP001": { "enabled": true },
+    "AP005": { "enabled": true, "options": { "maxRoles": 3 } }
+  },
+  "suppressions": [
+    {
+      "ruleId": "AP001",
+      "route": "/api/health",
+      "reason": "Health check is intentionally public"
+    }
+  ],
+  "scan": {
+    "excludePatterns": ["**/test/**"]
+  }
+}
+```
+
+## Supported Frameworks
+
+### Express.js
+```javascript
+app.get('/path', handler);
+router.post('/path', authMiddleware, handler);
+app.use('/prefix', router);
+```
+
+### NestJS
+```typescript
+@Controller('path')
+@UseGuards(AuthGuard)
+class MyController {
+  @Get()
+  @Roles('admin')
+  handler() {}
+}
+```
+
+### Fastify
+```javascript
+fastify.get('/path', { preHandler: [auth] }, handler);
+fastify.route({ method: 'GET', url: '/path', handler });
+```
+
+### Koa
+```javascript
+router.get('/path', authMiddleware, handler);
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Security Scan
+  run: npx @apiposture/cli scan --fail-on high -o json -f report.json
+```
+
+```yaml
+# GitLab CI
+security-scan:
+  script:
+    - npx @apiposture/cli scan --fail-on critical
+```
+
+## Environment Variables
+
+- `APIPOSTURE_LICENSE_KEY`: License key for Pro features
+
+## License
+
+MIT

package/dist/cli/commands/license/activate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createActivateCommand(): Command;
+//# sourceMappingURL=activate.d.ts.map

package/dist/cli/commands/license/activate.js

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import ora from 'ora';
+import { LicenseManager } from '../../../licensing/license-manager.js';
+export function createActivateCommand() {
+    return new Command('activate')
+        .description('Activate a license key')
+        .argument('<key>', 'License key to activate')
+        .action(async (key) => {
+        const spinner = ora('Activating license...').start();
+        try {
+            const manager = new LicenseManager();
+            const result = await manager.activate(key);
+            if (result.success) {
+                spinner.succeed('License activated successfully!');
+                console.log(`\nLicense Type: ${result.licenseType}`);
+                console.log(`Expires: ${result.expiresAt?.toLocaleDateString() ?? 'Never'}`);
+                console.log('\nEnabled features:');
+                for (const feature of result.features ?? []) {
+                    console.log(`  - ${feature}`);
+                }
+            }
+            else {
+                spinner.fail('License activation failed');
+                console.error(`Error: ${result.error}`);
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            spinner.fail('License activation failed');
+            console.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=activate.js.map

package/dist/cli/commands/license/deactivate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createDeactivateCommand(): Command;
+//# sourceMappingURL=deactivate.d.ts.map

package/dist/cli/commands/license/deactivate.js

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import ora from 'ora';
+import { LicenseManager } from '../../../licensing/license-manager.js';
+export function createDeactivateCommand() {
+    return new Command('deactivate')
+        .description('Deactivate the current license')
+        .action(async () => {
+        const spinner = ora('Deactivating license...').start();
+        try {
+            const manager = new LicenseManager();
+            const result = await manager.deactivate();
+            if (result.success) {
+                spinner.succeed('License deactivated successfully');
+            }
+            else {
+                spinner.fail('License deactivation failed');
+                console.error(`Error: ${result.error}`);
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            spinner.fail('License deactivation failed');
+            console.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=deactivate.js.map

package/dist/cli/commands/license/status.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createStatusCommand(): Command;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/license/status.js

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+import { LicenseManager } from '../../../licensing/license-manager.js';
+export function createStatusCommand() {
+    return new Command('status')
+        .description('Show current license status')
+        .action(async () => {
+        try {
+            const manager = new LicenseManager();
+            const status = await manager.getStatus();
+            console.log('\nLicense Status');
+            console.log('==============');
+            if (status.isActive) {
+                console.log(`Status: Active`);
+                console.log(`Type: ${status.licenseType}`);
+                console.log(`Expires: ${status.expiresAt?.toLocaleDateString() ?? 'Never'}`);
+                console.log('\nEnabled Features:');
+                for (const feature of status.features ?? []) {
+                    console.log(`  [x] ${feature}`);
+                }
+            }
+            else {
+                console.log('Status: Not licensed (Community Edition)');
+                console.log('\nTo unlock Pro features, activate a license key:');
+                console.log('  apiposture license activate <key>');
+                console.log('\nOr set the APIPOSTURE_LICENSE_KEY environment variable.');
+            }
+            console.log('');
+        }
+        catch (error) {
+            console.error('Failed to get license status');
+            console.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/cli/commands/scan.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createScanCommand(): Command;
+//# sourceMappingURL=scan.d.ts.map

package/dist/cli/commands/scan.js

@@ -0,0 +1,211 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import ora from 'ora';
+import { defaultScanOptions, parseClassificationList, parseMethodList, parseApiStyleList, parseRuleList, } from '../options.js';
+import { ProjectAnalyzer } from '../../core/analysis/project-analyzer.js';
+import { ExpressDiscoverer } from '../../core/discovery/express-discoverer.js';
+import { NestJSDiscoverer } from '../../core/discovery/nestjs-discoverer.js';
+import { FastifyDiscoverer } from '../../core/discovery/fastify-discoverer.js';
+import { KoaDiscoverer } from '../../core/discovery/koa-discoverer.js';
+import { RuleEngine } from '../../rules/rule-engine.js';
+import { getHighestSeverity } from '../../core/models/scan-result.js';
+import { severityOrder, parseSeverity } from '../../core/models/severity.js';
+import { TerminalFormatter } from '../../output/terminal-formatter.js';
+import { JsonFormatter } from '../../output/json-formatter.js';
+import { MarkdownFormatter } from '../../output/markdown-formatter.js';
+import { ConfigLoader } from '../../core/configuration/config-loader.js';
+export function createScanCommand() {
+    const command = new Command('scan')
+        .description('Scan a Node.js project for API security issues')
+        .argument('[path]', 'Path to the project to scan', '.')
+        .option('-o, --output <format>', 'Output format: terminal, json, markdown', 'terminal')
+        .option('-f, --output-file <path>', 'Write output to file')
+        .option('-c, --config <path>', 'Path to config file (.apiposture.json)')
+        .option('--severity <level>', 'Minimum severity: info, low, medium, high, critical')
+        .option('--fail-on <level>', 'Exit with code 1 if findings at this level or higher')
+        .option('--sort-by <field>', 'Sort by: severity, route, method, classification')
+        .option('--sort-dir <dir>', 'Sort direction: asc, desc')
+        .option('--classification <types>', 'Filter by classification (comma-separated)')
+        .option('--method <methods>', 'Filter by HTTP method (comma-separated)')
+        .option('--route-contains <str>', 'Filter routes containing string')
+        .option('--api-style <styles>', 'Filter by framework: express, nestjs, fastify, koa')
+        .option('--rule <rules>', 'Filter by rule ID (comma-separated)')
+        .option('--group-by <field>', 'Group endpoints by field')
+        .option('--no-color', 'Disable colors in output')
+        .option('--no-icons', 'Disable icons in output')
+        .action(async (projectPath, cmdOptions) => {
+        await runScan(projectPath, cmdOptions);
+    });
+    return command;
+}
+async function runScan(projectPath, cmdOptions) {
+    const absolutePath = path.resolve(projectPath);
+    // Validate project path exists
+    if (!fs.existsSync(absolutePath)) {
+        console.error(`Error: Path not found: ${absolutePath}`);
+        process.exit(1);
+    }
+    // Load config if specified (for future use with rule configuration)
+    const configPath = cmdOptions.config;
+    if (configPath) {
+        const configLoader = new ConfigLoader();
+        await configLoader.load(configPath);
+    }
+    // Parse options
+    const options = {
+        ...defaultScanOptions,
+        output: cmdOptions.output ?? 'terminal',
+        outputFile: cmdOptions.outputFile,
+        severity: cmdOptions.severity ? parseSeverity(cmdOptions.severity) : undefined,
+        failOn: cmdOptions.failOn ? parseSeverity(cmdOptions.failOn) : undefined,
+        sortBy: cmdOptions.sortBy,
+        sortDir: cmdOptions.sortDir,
+        classification: cmdOptions.classification
+            ? parseClassificationList(cmdOptions.classification)
+            : undefined,
+        method: cmdOptions.method
+            ? parseMethodList(cmdOptions.method)
+            : undefined,
+        routeContains: cmdOptions.routeContains,
+        apiStyle: cmdOptions.apiStyle
+            ? parseApiStyleList(cmdOptions.apiStyle)
+            : undefined,
+        rule: cmdOptions.rule
+            ? parseRuleList(cmdOptions.rule)
+            : undefined,
+        noColor: cmdOptions.color === false,
+        noIcons: cmdOptions.icons === false,
+    };
+    // Start scanning
+    const spinner = ora({
+        text: 'Scanning project...',
+        isSilent: options.output !== 'terminal',
+    }).start();
+    try {
+        // Create analyzer
+        const analyzer = new ProjectAnalyzer();
+        // Register discoverers based on api-style filter or all by default
+        const apiStyles = options.apiStyle ?? ['express', 'nestjs', 'fastify', 'koa'];
+        if (apiStyles.includes('express')) {
+            analyzer.registerDiscoverer(new ExpressDiscoverer());
+        }
+        if (apiStyles.includes('nestjs')) {
+            analyzer.registerDiscoverer(new NestJSDiscoverer());
+        }
+        if (apiStyles.includes('fastify')) {
+            analyzer.registerDiscoverer(new FastifyDiscoverer());
+        }
+        if (apiStyles.includes('koa')) {
+            analyzer.registerDiscoverer(new KoaDiscoverer());
+        }
+        // Run analysis
+        let result = await analyzer.analyze(absolutePath);
+        // Apply rule evaluation
+        const ruleEngine = new RuleEngine();
+        const findings = ruleEngine.evaluate(result.endpoints);
+        result = { ...result, findings };
+        // Apply filters
+        result = applyFilters(result, options);
+        spinner.succeed(`Scan complete`);
+        // Format and output
+        const formatter = getFormatter(options);
+        const output = formatter.format(result);
+        if (options.outputFile) {
+            fs.writeFileSync(options.outputFile, output, 'utf-8');
+            console.log(`Output written to: ${options.outputFile}`);
+        }
+        else {
+            console.log(output);
+        }
+        // Check fail-on condition
+        if (options.failOn) {
+            const highest = getHighestSeverity(result);
+            if (highest && severityOrder[highest] >= severityOrder[options.failOn]) {
+                process.exit(1);
+            }
+        }
+    }
+    catch (error) {
+        spinner.fail('Scan failed');
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+function applyFilters(result, options) {
+    let { endpoints, findings } = result;
+    // Filter by severity
+    if (options.severity) {
+        const minSeverity = severityOrder[options.severity];
+        findings = findings.filter((f) => severityOrder[f.severity] >= minSeverity);
+    }
+    // Filter by classification
+    if (options.classification && options.classification.length > 0) {
+        endpoints = endpoints.filter((e) => options.classification.includes(e.authorization.classification));
+        findings = findings.filter((f) => options.classification.includes(f.endpoint.authorization.classification));
+    }
+    // Filter by method
+    if (options.method && options.method.length > 0) {
+        endpoints = endpoints.filter((e) => options.method.includes(e.method));
+        findings = findings.filter((f) => options.method.includes(f.endpoint.method));
+    }
+    // Filter by route
+    if (options.routeContains) {
+        const searchStr = options.routeContains.toLowerCase();
+        endpoints = endpoints.filter((e) => e.route.toLowerCase().includes(searchStr));
+        findings = findings.filter((f) => f.endpoint.route.toLowerCase().includes(searchStr));
+    }
+    // Filter by api style
+    if (options.apiStyle && options.apiStyle.length > 0) {
+        endpoints = endpoints.filter((e) => options.apiStyle.includes(e.type));
+        findings = findings.filter((f) => options.apiStyle.includes(f.endpoint.type));
+    }
+    // Filter by rule
+    if (options.rule && options.rule.length > 0) {
+        findings = findings.filter((f) => options.rule.includes(f.ruleId));
+    }
+    // Apply sorting
+    if (options.sortBy) {
+        const dir = options.sortDir === 'desc' ? -1 : 1;
+        endpoints = [...endpoints].sort((a, b) => {
+            switch (options.sortBy) {
+                case 'route':
+                    return dir * a.route.localeCompare(b.route);
+                case 'method':
+                    return dir * a.method.localeCompare(b.method);
+                case 'classification':
+                    return dir * a.authorization.classification.localeCompare(b.authorization.classification);
+                default:
+                    return 0;
+            }
+        });
+        findings = [...findings].sort((a, b) => {
+            switch (options.sortBy) {
+                case 'severity':
+                    return dir * (severityOrder[a.severity] - severityOrder[b.severity]);
+                case 'route':
+                    return dir * a.endpoint.route.localeCompare(b.endpoint.route);
+                case 'method':
+                    return dir * a.endpoint.method.localeCompare(b.endpoint.method);
+                default:
+                    return 0;
+            }
+        });
+    }
+    return { ...result, endpoints, findings };
+}
+function getFormatter(options) {
+    switch (options.output) {
+        case 'json':
+            return new JsonFormatter();
+        case 'markdown':
+            return new MarkdownFormatter();
+        case 'terminal':
+        default:
+            return new TerminalFormatter({
+                noColor: options.noColor,
+                noIcons: options.noIcons,
+            });
+    }
+}
+//# sourceMappingURL=scan.js.map

package/dist/cli/options.d.ts

@@ -0,0 +1,27 @@
+import { Severity } from '../core/models/severity.js';
+import { SecurityClassification } from '../core/models/security-classification.js';
+import { HttpMethod } from '../core/models/http-method.js';
+import { EndpointType } from '../core/models/endpoint-type.js';
+export interface ScanOptions {
+    output: 'terminal' | 'json' | 'markdown';
+    outputFile?: string;
+    config?: string;
+    severity?: Severity;
+    failOn?: Severity;
+    sortBy?: 'severity' | 'route' | 'method' | 'classification';
+    sortDir?: 'asc' | 'desc';
+    classification?: SecurityClassification[];
+    method?: HttpMethod[];
+    routeContains?: string;
+    apiStyle?: EndpointType[];
+    rule?: string[];
+    groupBy?: string;
+    noColor: boolean;
+    noIcons: boolean;
+}
+export declare const defaultScanOptions: ScanOptions;
+export declare function parseClassificationList(value: string): SecurityClassification[];
+export declare function parseMethodList(value: string): HttpMethod[];
+export declare function parseApiStyleList(value: string): EndpointType[];
+export declare function parseRuleList(value: string): string[];
+//# sourceMappingURL=options.d.ts.map