codeant-cli 0.5.4 → 0.5.5

package/scans.md

@@ -0,0 +1,263 @@
+# `codeant scans`
+
+Fetch and explore scan results from CodeAnt.
+
+```bash
+codeant scans <subcommand> [options]
+```
+
+---
+
+## Subcommands
+
+### `scans orgs`
+
+List authenticated organizations.
+
+```bash
+codeant scans orgs
+```
+
+---
+
+### `scans repos`
+
+List repositories for an organization.
+
+```bash
+codeant scans repos [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--org <org>` | Organization name (auto-picked when only one is authenticated) |
+
+**Examples:**
+
+```bash
+# List repos (auto-selects org if only one)
+codeant scans repos
+
+# List repos for a specific org
+codeant scans repos --org my-org
+```
+
+---
+
+### `scans history`
+
+Show scan history for a repository.
+
+```bash
+codeant scans history --repo <owner/repo> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--repo <repo>` | **(required)** Repository in `owner/repo` format |
+| `--branch <name>` | Filter by branch name |
+| `--since <iso>` | Show scans since ISO date (e.g. `2024-01-01`) |
+| `--limit <n>` | Max results (default: `20`) |
+
+**Examples:**
+
+```bash
+# Show last 20 scans for a repo
+codeant scans history --repo acme/backend
+
+# Filter to a specific branch
+codeant scans history --repo acme/backend --branch main
+
+# Show scans since a date
+codeant scans history --repo acme/backend --since 2024-06-01
+
+# Show up to 50 results
+codeant scans history --repo acme/backend --limit 50
+```
+
+---
+
+### `scans get`
+
+Show scan metadata and a severity/category summary. Does not include individual findings.
+
+```bash
+codeant scans get --repo <owner/repo> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--repo <repo>` | **(required)** Repository in `owner/repo` format |
+| `--scan <sha>` | Specific commit SHA to use |
+| `--branch <name>` | Resolve latest scan on this branch |
+| `--types <list>` | Comma-separated scan types (default: `all`) |
+| `--quiet` | Suppress progress output |
+
+**Examples:**
+
+```bash
+# Get latest scan summary for a repo
+codeant scans get --repo acme/backend
+
+# Get scan for a specific commit
+codeant scans get --repo acme/backend --scan abc1234
+
+# Get latest scan on a branch
+codeant scans get --repo acme/backend --branch main
+
+# Only include SAST and secrets types
+codeant scans get --repo acme/backend --types sast,secrets
+
+# Suppress progress output
+codeant scans get --repo acme/backend --quiet
+```
+
+---
+
+### `scans results`
+
+Fetch full scan findings for a repository.
+
+```bash
+codeant scans results --repo <owner/repo> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--repo <repo>` | **(required)** Repository in `owner/repo` format |
+| `--scan <sha>` | Specific commit SHA to use |
+| `--branch <name>` | Resolve latest scan on this branch |
+| `--types <list>` | Comma-separated types: `sast`, `sca`, `secrets`, `iac`, `dead_code`, `sbom`, `anti_patterns`, `docstring`, `complex_functions`, `all` (default: `all`) |
+| `--severity <list>` | Filter by severity (e.g. `critical,high`) |
+| `--path <glob>` | Filter by file path glob |
+| `--check <regex>` | Filter by check ID or name (regex) |
+| `--include-dismissed` | Include dismissed findings (excluded by default) |
+| `--format <fmt>` | Output format: `json`, `sarif`, `csv`, `md`, `table` (default: `json`) |
+| `--output <path>` | Write output to file instead of stdout |
+| `--fields <list>` | Project findings to a subset of fields (comma-separated) |
+| `--limit <n>` | Max findings per page (default: `100`) |
+| `--offset <n>` | Pagination offset (default: `0`) |
+| `--fail-fast` | Exit `3` on first category fetch failure |
+| `--no-color` | Disable ANSI color (auto-disabled when not a TTY) |
+| `--quiet` | Suppress progress output on stderr |
+
+**Examples:**
+
+```bash
+# Fetch all findings (JSON)
+codeant scans results --repo acme/backend
+
+# Fetch only critical and high severity findings
+codeant scans results --repo acme/backend --severity critical,high
+
+# Fetch SAST findings only
+codeant scans results --repo acme/backend --types sast
+
+# Filter to a specific file path
+codeant scans results --repo acme/backend --path 'src/**/*.ts'
+
+# Filter by check name using regex
+codeant scans results --repo acme/backend --check 'sql-injection'
+
+# Output as a Markdown table
+codeant scans results --repo acme/backend --format md
+
+# Output as SARIF to a file
+codeant scans results --repo acme/backend --format sarif --output results.sarif
+
+# Include dismissed findings
+codeant scans results --repo acme/backend --include-dismissed
+
+# Paginate through results
+codeant scans results --repo acme/backend --limit 50 --offset 100
+
+# Project only specific fields
+codeant scans results --repo acme/backend --fields id,severity,message,path
+```
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error |
+| `3` | Category fetch failure (with `--fail-fast`) |
+
+---
+
+### `scans dismissed`
+
+List dismissed alerts for a repository.
+
+```bash
+codeant scans dismissed --repo <owner/repo> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--repo <repo>` | **(required)** Repository in `owner/repo` format |
+| `--analysis-type <type>` | Analysis type: `security` or `secrets` (default: `security`) |
+
+**Examples:**
+
+```bash
+# List dismissed security alerts
+codeant scans dismissed --repo acme/backend
+
+# List dismissed secrets alerts
+codeant scans dismissed --repo acme/backend --analysis-type secrets
+```
+
+---
+
+### `scans start-scan`
+
+Trigger a new analysis run for a repository.
+
+```bash
+codeant scans start-scan [options]
+```
+
+All options are optional — `repo`, `branch`, and `commit` are auto-detected from the local git context when not provided.
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--repo <repo>` | Repository in `owner/repo` format (auto-detected from git remote) |
+| `--branch <name>` | Branch to scan (auto-detected from current checkout) |
+| `--commit <sha>` | Commit SHA to scan (resolved from remote HEAD of branch if omitted) |
+| `--include <paths>` | Comma-separated file path glob patterns to include |
+| `--exclude <paths>` | Comma-separated file path glob patterns to exclude |
+
+**Examples:**
+
+```bash
+# Zero-config — auto-detects repo, branch, and latest commit
+codeant scans start-scan
+
+# Explicit repo and branch
+codeant scans start-scan --repo your-org/your-repo --branch main
+
+# Explicit commit SHA
+codeant scans start-scan \
+  --repo your-org/your-repo \
+  --branch main \
+  --commit b509bffa1721da442f35a7ccab969822711a67f0
+
+# Scan only specific files
+codeant scans start-scan \
+  --branch main \
+  --include "src/main.py,src/utils.py" \
+  --exclude "tests/,*.md"
+```

package/src/api/tenant.js

@@ -0,0 +1,54 @@
+import { validateConnection } from '../scans/connectionHandler.js';
+
+const SERVICE_ALIASES = { azure_devops: 'azuredevops', ado: 'azuredevops' };
+const PROVIDER_BASE_FIELDS = {
+  github: 'github_base_url',
+  gitlab: 'gitlab_base_url',
+  bitbucket: 'bitbucket_base_url',
+  azuredevops: 'azure_devops_base_url',
+};
+
+export function normalizeService(value) {
+  const service = String(value || '').trim().toLowerCase();
+  return SERVICE_ALIASES[service] || service;
+}
+
+export async function resolveCliTenant({ org, service, providerBaseUrl } = {}) {
+  const validation = await validateConnection();
+  if (!validation.success) {
+    throw new Error(validation.error || 'Unable to load authenticated CodeAnt organizations.');
+  }
+  const requestedService = normalizeService(service);
+  const candidates = (validation.connections || []).filter((connection) => {
+    const orgMatches = !org || connection.organizationName === org;
+    const serviceMatches = !requestedService || normalizeService(connection.service) === requestedService;
+    return orgMatches && serviceMatches;
+  });
+  if (candidates.length === 0) {
+    throw new Error('No authenticated organization matches --org/--service. Run `codeant scans orgs` to list available connections.');
+  }
+  if (candidates.length > 1) {
+    throw new Error('More than one organization matches. Pass both --org and --service; run `codeant scans orgs` to list values.');
+  }
+
+  const connection = candidates[0];
+  const normalizedService = normalizeService(connection.service);
+  const baseField = PROVIDER_BASE_FIELDS[normalizedService];
+  if (!baseField) throw new Error(`Application APIs are not supported for service ${connection.service}.`);
+  const organization = org || connection.organizationName;
+  const baseUrl = providerBaseUrl || connection.baseUrl;
+  if (!baseUrl) {
+    throw new Error('The provider base URL is unavailable. Pass --provider-base-url explicitly.');
+  }
+  return {
+    organization,
+    service: normalizedService,
+    providerBaseUrl: baseUrl,
+    requestBody: {
+      org: organization,
+      organization,
+      service: normalizedService,
+      [baseField]: baseUrl,
+    },
+  };
+}

package/src/commands/api/index.js

@@ -0,0 +1,33 @@
+import { runApiRequest } from './request.js';
+
+function collect(value, previous) {
+  return [...previous, value];
+}
+
+export default function registerApiCommands(program, { runCmd }) {
+  const api = program
+    .command('api')
+    .description('Call any authenticated CodeAnt application API');
+
+  api
+    .command('request <method> <path>')
+    .description('Send an authenticated request to a relative CodeAnt API path')
+    .option('--query <json>', 'Query parameters as a JSON object')
+    .option('--body <json>', 'JSON request body')
+    .option('--body-file <path>', 'Read the JSON request body from a file')
+    .option('--org <organization>', 'Authenticated CodeAnt organization')
+    .option('--service <provider>', 'SCM provider: github, gitlab, bitbucket, or azuredevops')
+    .option('--provider-base-url <url>', 'Provider base URL override for self-hosted SCMs')
+    .option('-H, --header <header>', 'Additional header (repeatable, "Name: value")', collect, [])
+    .action((method, path, options) => runCmd(() => runApiRequest({
+      method,
+      path,
+      query: options.query,
+      body: options.body,
+      bodyFile: options.bodyFile,
+      headers: options.header,
+      org: options.org,
+      service: options.service,
+      providerBaseUrl: options.providerBaseUrl,
+    })));
+}

package/src/commands/api/request.js

@@ -0,0 +1,109 @@
+import { readFile } from 'node:fs/promises';
+
+import { fetchApiResponse } from '../../utils/fetchApi.js';
+import { resolveCliTenant } from '../../api/tenant.js';
+
+const METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+const BLOCKED_HEADERS = new Set([
+  'authorization',
+  'cookie',
+  'host',
+  'content-length',
+  'x-codeant-cli-org',
+  'x-codeant-cli-service',
+  'x-codeant-cli-base-url',
+]);
+
+export function normalizeApiPath(path) {
+  const value = String(path || '').trim();
+  if (!value.startsWith('/') || value.startsWith('//')) {
+    throw new Error('API path must be relative to the configured CodeAnt API URL and start with `/`.');
+  }
+  const resolved = new URL(value, 'https://codeant.invalid');
+  if (resolved.origin !== 'https://codeant.invalid') {
+    throw new Error('API path must stay on the configured CodeAnt API host.');
+  }
+  return `${resolved.pathname}${resolved.search}`;
+}
+
+export function parseJsonObject(value, label) {
+  const parsed = parseJsonValue(value, label);
+  if (parsed === undefined) return undefined;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return parsed;
+}
+
+export function parseJsonValue(value, label) {
+  if (value === undefined || value === null || value === '') return undefined;
+  let parsed;
+  try {
+    parsed = typeof value === 'string' ? JSON.parse(value) : value;
+  } catch (error) {
+    throw new Error(`Invalid ${label} JSON: ${error.message}`);
+  }
+  return parsed;
+}
+
+export function parseHeaders(values = []) {
+  const headers = {};
+  for (const entry of values || []) {
+    const separator = String(entry).indexOf(':');
+    if (separator < 1) throw new Error(`Invalid header ${JSON.stringify(entry)}; expected "Name: value".`);
+    const name = String(entry).slice(0, separator).trim();
+    const value = String(entry).slice(separator + 1).trim();
+    if (BLOCKED_HEADERS.has(name.toLowerCase())) {
+      throw new Error(`Header ${name} is managed by CodeAnt CLI and cannot be overridden.`);
+    }
+    headers[name] = value;
+  }
+  return headers;
+}
+
+export async function runApiRequest({
+  path,
+  method,
+  query,
+  body,
+  bodyFile,
+  headers,
+  org,
+  service,
+  providerBaseUrl,
+} = {}) {
+  const normalizedMethod = String(method || 'GET').toUpperCase();
+  if (!METHODS.has(normalizedMethod)) {
+    throw new Error(`Unsupported method ${normalizedMethod}. Use ${[...METHODS].join(', ')}.`);
+  }
+  if (body !== undefined && bodyFile) {
+    throw new Error('Use either --body or --body-file, not both.');
+  }
+
+  let requestBody = parseJsonValue(body, 'body');
+  if (bodyFile) {
+    requestBody = parseJsonValue(await readFile(bodyFile, 'utf8'), 'body file');
+  }
+
+  const tenant = await resolveCliTenant({ org, service, providerBaseUrl });
+  if (!['GET', 'HEAD'].includes(normalizedMethod)) {
+    if (requestBody !== undefined && (!requestBody || typeof requestBody !== 'object' || Array.isArray(requestBody))) {
+      throw new Error('Authenticated application API request bodies must be JSON objects.');
+    }
+    requestBody = { ...tenant.requestBody, ...(requestBody || {}) };
+  }
+  const response = await fetchApiResponse(normalizeApiPath(path), {
+    method: normalizedMethod,
+    query: parseJsonObject(query, 'query'),
+    body: requestBody,
+    headers: parseHeaders(headers),
+    allowHttpError: true,
+    tenant,
+  });
+  return {
+    ok: response.ok,
+    status: response.status,
+    tenant: tenant.requestBody,
+    data: response.data,
+  };
+}

package/src/commands/findings/index.js

@@ -0,0 +1,197 @@
+import { runRepos } from '../scans/repos.js';
+import { runResults } from '../scans/results.js';
+import { setQuiet, setNoColor } from '../scans/lib/log.js';
+import { setNoColor as tableSetNoColor } from '../scans/formatters/table.js';
+import { runHotlistGet, runHotlistList } from '../../hotlist/client.js';
+import { runOrganizationAntipatterns } from '../../findings/antipatterns.js';
+import { runCloudFindingGet, runCloudFindings, runCloudHistory } from '../../findings/cloud.js';
+import { runPentestHistory, runPentestIssues, runPentestReport } from '../../findings/pentest.js';
+
+function addTenantOptions(command) {
+  return command
+    .option('--org <org>', 'Organization name (auto-picked when unambiguous)')
+    .option('--service <service>', 'github, gitlab, bitbucket, or azuredevops')
+    .option('--provider-base-url <url>', 'Override the authenticated provider base URL');
+}
+
+function tenantOptions(options) {
+  return {
+    org: options.org,
+    service: options.service,
+    providerBaseUrl: options.providerBaseUrl,
+  };
+}
+
+function addHotlistOptions(command) {
+  return addTenantOptions(command)
+    .option('--search <text>', 'Search title, repository, path, package, CVE, or check ID')
+    .option('--type <values>', 'Comma-separated types: SAST,SCA,Secrets,IaC,Infrastructure,AI Exploitation')
+    .option('--location <values>', 'Comma-separated repositories or cloud accounts')
+    .option('--severity <values>', 'Comma-separated severities')
+    .option('--ticket-status <values>', 'created,not_created')
+    .option('--compliance <values>', 'Comma-separated compliance frameworks')
+    .option('--validation <values>', 'Comma-separated validation flags')
+    .option('--limit <n>', 'Page size from 1 to 100', Number, 30)
+    .option('--cursor <cursor>', 'Continue from a previous next_cursor')
+    .option('--all', 'Fetch every matching page', false)
+    .option('--max-wait <seconds>', 'Wait for an initial Hotlist build', Number, 60);
+}
+
+function hotlistOptions(options) {
+  return {
+    ...tenantOptions(options),
+    search: options.search,
+    types: options.type,
+    locations: options.location,
+    severities: options.severity,
+    ticketStatuses: options.ticketStatus,
+    compliance: options.compliance,
+    validation: options.validation,
+    limit: options.limit,
+    cursor: options.cursor,
+    all: options.all,
+    maxWaitSeconds: options.maxWait,
+  };
+}
+
+function addCloudScopeOptions(command) {
+  return addTenantOptions(command)
+    .requiredOption('--provider <provider>', 'Cloud provider: aws, azure, or gcp')
+    .option('--kind <kind>', 'Finding kind: cspm, vm, or container', 'cspm')
+    .requiredOption('--scan-id <id>', 'Cloud scan ID')
+    .option('--account-id <id>', 'AWS account ID')
+    .option('--tenant-id <id>', 'Azure tenant ID')
+    .option('--project-id <id>', 'GCP project ID')
+    .option('--cloud-service <name>', 'Provider service filter or finding service');
+}
+
+function cloudOptions(options) {
+  return {
+    ...tenantOptions(options),
+    provider: options.provider,
+    kind: options.kind,
+    scanId: options.scanId,
+    accountId: options.accountId,
+    tenantId: options.tenantId,
+    projectId: options.projectId,
+    cloudService: options.cloudService,
+    severity: options.severity,
+    status: options.status,
+    framework: options.framework,
+    subscriptionId: options.subscriptionId,
+    exploitAttemptedOnly: options.exploitAttemptedOnly,
+    minDaysUnused: options.minDaysUnused,
+  };
+}
+
+function runRepoResults(options) {
+  setQuiet(options.quiet);
+  if (options.noColor) {
+    setNoColor(true);
+    tableSetNoColor(true);
+  }
+  return runResults({
+    repo: options.repo,
+    scan: options.scan,
+    branch: options.branch,
+    types: options.types,
+    severity: options.severity,
+    path: options.path,
+    check: options.check,
+    filterDismissed: options.filterDismissed || false,
+    includeFalsePositives: options.falsePositives ?? true,
+    format: options.format,
+    output: options.output,
+    fields: options.fields,
+    limit: options.limit,
+    offset: options.offset,
+    failFast: options.failFast || false,
+  });
+}
+
+export default function registerFindingsCommands(program, { runCmd }) {
+  const findings = program.command('findings').description('Access CodeAnt findings from repositories, Hotlist, cloud security, and pentesting');
+
+  findings
+    .command('repos')
+    .description('List repositories available for repo-level findings')
+    .option('--org <org>', 'Organization name (auto-picked when only one is authenticated)')
+    .action((options) => runCmd(() => runRepos({ org: options.org })));
+
+  findings
+    .command('repo')
+    .description('Fetch repo-level SAST, SCA, IaC, secrets, anti-pattern, and quality findings')
+    .requiredOption('--repo <repo>', 'Repository (owner/repo)')
+    .option('--scan <sha>', 'Specific commit SHA to use')
+    .option('--branch <name>', 'Resolve latest scan on this branch')
+    .option('--types <list>', 'Comma-separated types: sast,sca,secrets,iac,dead_code,sbom,anti_patterns,docstring,complex_functions,all', 'all')
+    .option('--severity <list>', 'Filter by severity')
+    .option('--path <glob>', 'Filter by file path glob')
+    .option('--check <regex>', 'Filter by check ID or name')
+    .option('--filter-dismissed', 'Exclude dismissed findings')
+    .option('--no-false-positives', 'Exclude false positives')
+    .option('--format <fmt>', 'json|sarif|csv|md|table', 'json')
+    .option('--output <path>', 'Write output to a file')
+    .option('--fields <list>', 'Project findings to a subset of fields')
+    .option('--limit <n>', 'Max findings per page', Number, 100)
+    .option('--offset <n>', 'Pagination offset', Number, 0)
+    .option('--fail-fast', 'Stop on the first category error')
+    .option('--no-color', 'Disable ANSI color')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (options) => {
+      try { await runRepoResults(options); }
+      catch (err) {
+        process.stderr.write(JSON.stringify({ error: err.message }) + '\n');
+        process.exitCode = err.exitCode ?? 1;
+      }
+    });
+
+  addHotlistOptions(findings.command('list').description('List organization-wide Hotlist findings'))
+    .action((options) => runCmd(() => runHotlistList(hotlistOptions(options))));
+
+  addTenantOptions(findings.command('get <finding-id>').description('Get one Hotlist finding by its stable ID'))
+    .option('--max-wait <seconds>', 'Wait for an initial Hotlist build', Number, 60)
+    .action((findingId, options) => runCmd(() => runHotlistGet({
+      findingId,
+      ...tenantOptions(options),
+      maxWaitSeconds: options.maxWait,
+    })));
+
+  addTenantOptions(findings.command('antipatterns').description('List anti-pattern findings across selected or all organization repositories'))
+    .option('--repos <repos>', 'Comma-separated owner/repo values; defaults to every repository')
+    .action((options) => runCmd(() => runOrganizationAntipatterns({ ...tenantOptions(options), repos: options.repos })));
+
+  const cloud = findings.command('cloud').description('Cloud security CSPM, VM, and container findings');
+  addTenantOptions(cloud.command('history').description('List cloud scan history, or latest scans'))
+    .option('--provider <provider>', 'aws, azure, gcp, or all', 'all')
+    .option('--kind <kind>', 'Finding kind: cspm, vm, or container', 'cspm')
+    .option('--latest', 'Return only latest CSPM scans')
+    .action((options) => runCmd(() => runCloudHistory({ ...tenantOptions(options), provider: options.provider, kind: options.kind, latest: options.latest })));
+
+  addCloudScopeOptions(cloud.command('list').description('List findings for a cloud scan'))
+    .option('--severity <value>', 'Severity filter')
+    .option('--status <value>', 'Finding status filter')
+    .option('--framework <value>', 'Compliance framework filter')
+    .option('--subscription-id <id>', 'Azure subscription ID filter')
+    .option('--exploit-attempted-only', 'AWS findings with validation attempts only')
+    .option('--min-days-unused <n>', 'Minimum unused age in days', Number)
+    .action((options) => runCmd(() => runCloudFindings(cloudOptions(options))));
+
+  addCloudScopeOptions(cloud.command('get').description('Get one cloud finding with full detail'))
+    .requiredOption('--uid <uid>', 'Finding UID')
+    .action((options) => runCmd(() => runCloudFindingGet({ ...cloudOptions(options), uid: options.uid })));
+
+  const pentest = findings.command('pentest').description('Pentest histories, issues, and reports');
+  addTenantOptions(pentest.command('history').description('List pentest engagements'))
+    .action((options) => runCmd(() => runPentestHistory(tenantOptions(options))));
+
+  addTenantOptions(pentest.command('issues').description('List all issues for a pentest engagement'))
+    .requiredOption('--report-id <id>', 'Pentest report/engagement ID')
+    .option('--variant <variant>', 'prod or test', 'prod')
+    .action((options) => runCmd(() => runPentestIssues({ ...tenantOptions(options), reportId: options.reportId, variant: options.variant })));
+
+  addTenantOptions(pentest.command('report').description('Get the full pentest customer report'))
+    .requiredOption('--report-id <id>', 'Pentest report/engagement ID')
+    .option('--variant <variant>', 'prod or test', 'prod')
+    .action((options) => runCmd(() => runPentestReport({ ...tenantOptions(options), reportId: options.reportId, variant: options.variant })));
+}