@vigilbase/cli/SECURITY.md

Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.

# Security command reference

All commands start with `vigilbase security`. Sign in with `vigilbase login` first (signing in isn't supported on Windows yet). Commands use the configured One origin and its authenticated `/api/flarehawk` boundary. One independently checks permissions and maps the current organization to its security tenant. Internal operators can supply `--customer-id <One customer UUID>` for validated View-as access; this never supplies an upstream organization identity.

Every operation below is **GET/read-only**, except `incidents update`, which is **PATCH/write** and requires `--confirm` plus server service-write permission. Reads require server service-read permission. No command directly accesses the retained service, runs archived chat, changes remediation authority, or approves provider effects.

Append `--json` for the complete validated wire envelope, including evidence, total counts, pagination cursors, warnings, and unavailable states. Text output preserves full resource IDs, sanitizes terminal control characters, and displays nested results. `--timeout <milliseconds>` controls request timeout; analytical queries can need `--timeout 120000`.

All endpoint paths in the tables are relative to `/api/flarehawk`. `<id>`, `<asset>`, `<connection>`, and `<job>` are UUIDs copied from the relevant inventories. Unsupported filters and extra positional arguments are rejected. `get` aliases `show` on incidents, connections, reports, and alerts; `ls` aliases `list` on incidents, connections, and reports.

## Incidents, signals, logs, and evidence

| Grammar after `security` | Flags | Endpoint |
|---|---|---|
| `[overview]` | None | `/dashboard/overview` |
| `incidents [list]` | `--limit`, `--offset`, `--status`, `--severity`, `--attack-category`, `--order-by`, `--order-direction` | `/incidents` |
| `incidents show <id>` | None | `/incidents/<id>` |
| `incidents timeline <id>` | `--limit`, `--before` | `/incidents/<id>/timeline` |
| `incidents fabric <id>` | `--dataset`, `--min-weight`, `--limit` | `/incidents/<id>/fabric` |
| `incidents share-links <id>` | None | `/incidents/<id>/share-links` |
| `incidents update <id> <status> --confirm` | `--note` | **PATCH** `/incidents/<id>`; JSON body `{status,note?}` |
| `alerts [list]` | `--limit`, `--asset-id`, `--start` | `/alerts`; `start` maps to `since` |
| `alerts show <id>` | None | `/alerts/<id>` |
| `logs` | `--limit`, `--asset-id`, `--provider`, `--dataset`, `--search`, `--start`, `--end`, `--sort`, `--frs-min`, `--cursor` | `/logs` |
| `audit` | `--limit`, `--cursor`, `--action-prefix`, `--outcome` | `/vigilbase-one/audit-events` |

Incident list statuses: `open`, `active`, `acknowledged`, `investigating`, `mitigating`, `mitigated`, `resolved`, `false_positive`. Update statuses: `acknowledged`, `mitigating`, `resolved`, `false_positive`. Severity: `critical`, `high`, `medium`, `low`. Ordering: `last_alert_at`, `first_alert_at`, `created_at`, `severity_rank`, `combined_score`, `alert_count`; direction: `asc` or `desc`. Hyphenated filter names map to snake_case on the wire. Incident updates report a `feedback_sync_error` warning when status changed but signal feedback synchronization failed; confirmation does not bypass server authorization.

Logs require `--start` and `--end` together as ISO timestamps with an explicit timezone; start must precede end. They map to `start_time` and `end_time`. Sort: `ts`, `frs`, or `frs_desc`; FRS minimum: integer 0–100. Other hyphenated filter names map to snake_case. Audit outcome: `success`, `failure`, or `denied`; `--action-prefix` maps to `action_prefix`. Alerts accept a single ISO `--start` timestamp as the lower bound.

## Assets, providers, and connection health

| Grammar after `security` | Flags | Endpoint |
|---|---|---|
| `assets` | None | `/domains` |
| `assets allowlist <asset>` | None | `/domains/<asset>/allowlist` |
| `assets blocklist <asset>` | None | `/domains/<asset>/blocklist` |
| `assets remediation <asset>` | None | `/assets/<asset>/remediation-settings` |
| `assets autonomy <asset>` | None | `/assets/<asset>/vigil-autonomy` |
| `assets datasets <asset>` | None | `/fabric/assets/<asset>/datasets` |
| `assets graph <asset>` | `--dataset`, `--hours`, `--min-weight`, `--limit` | `/fabric/assets/<asset>/graph` |
| `fabric default-asset` | None | `/fabric/default-asset` |
| `detections --asset-id <asset>` | None | `/detections?asset_id=<asset>` |
| `providers` | None | `/providers?connectable=false` |
| `connections [list]` | None | `/connections` |
| `connections show <connection>` | None | `/connections/<connection>` |
| `connections available-assets <connection>` | None | `/connections/<connection>/available-assets` |
| `connections remediation <connection>` | None | `/connections/<connection>/remediation-settings` |
| `connections logpush-status <connection> <job>` | None | `/connections/<connection>/logpush-jobs/<job>/status` |
| `connections worker-stats <connection> <job>` | None | `/connections/<connection>/worker-routes/<job>/stats` |

Detections are configured per asset, and the API has no list for the whole tenant, so `--asset-id` is required; without it the CLI stops before any request. Take asset IDs from `security assets`.

Graph `--hours` maps to `window_hours`; `--min-weight` maps to `min_weight`. Incident graphs use the incident window and reject `--hours`. IP lists retain enforcement verification and synchronization status. Connection health includes stored state, provider status, receipt health, and available warnings. Credential-bearing HEC profile retrieval is outside this command set.

## Analytics and Cloudflare security

The time-window flags **W** are `--hours`, `--start`, `--end`, and `--asset-id`. Default: 24 hours. `--hours` is an integer 1–720. An explicit ISO `--start`/`--end` pair replaces `--hours`; these forms cannot be combined. `--asset-id` narrows the authenticated tenant's data. Wire keys are `hours`, `start`, `end`, and `asset_id`.

| Grammar after `security` | Flags | Endpoint |
|---|---|---|
| `analytics [overview]` | W, `--metrics` | `/analytics` |
| `analytics security-analysis` | W | `/analytics/security-analysis` |
| `analytics bot-activity` | W | `/analytics/bot-activity` |
| `analytics top-attacker-ips` | W | `/analytics/top-attacker-ips` |
| `analytics bot-asns` | W | `/analytics/bot-asns` |
| `analytics dns-security` | W | `/analytics/dns-security` |
| `analytics page-shield` | W | `/analytics/page-shield` |
| `analytics provider-events` | Required `--provider`, `--dataset`, `--start`, `--end`; optional `--asset-id`, `--search`, `--limit` | `/analytics/provider-events` |
| `zero-trust device-health` | W | `/zero-trust/device-health` |
| `zero-trust app-tests` | W | `/zero-trust/app-tests` |
| `zero-trust gateway <dns\|http\|network>` | W | `/zero-trust/gateway?surface=…` |
| `zero-trust access` | W | `/zero-trust/access` |
| `zero-trust sessions` | W | `/zero-trust/sessions` |
| `zero-trust device-posture` | W | `/zero-trust/device-posture` |
| `cloudflare-account [inventory]` | None | `/cloudflare-account/inventory` |
| `cloudflare-account audit` | W | `/cloudflare-account/audit` |
| `cloudflare-account ingestion` | W | `/cloudflare-account/ingestion` |
| `cloudflare-account posture` | W | `/cloudflare-account/posture` |

Analytics metrics are a comma-separated selection of `summary`, `hourly`, `by_domain`, `by_dataset`, `response_status`, `waf_scores`, `alerts`, `geographic`, `top_paths`, `waf_rules`, and `performance`. Default: `hourly,by_domain,by_dataset`.

Provider events map `--provider` to `provider_id`, `--dataset` to `dataset_id`, and `--asset-id` to `asset_ids`; start/end retain their names. Search is limited to 200 characters. Provider/dataset response identity and Gateway surface identity must match the request. `unavailable` results stay explicitly unavailable rather than implying healthy empty data.

## Notifications, reports, intelligence, and personal settings

| Grammar after `security` | Flags | Endpoint |
|---|---|---|
| `notifications [list]` | `--limit` | `/notifications` |
| `notifications settings` | None | `/notifications/settings` |
| `notifications preferences` | None | `/notifications/preferences` |
| `notifications slack-channels` | None | `/notifications/slack/channels` |
| `reports [list]` | `--limit`, `--offset` | `/reports` |
| `reports show <id>` | None | `/reports/<id>` |
| `reports settings` | None | `/reports/settings` |
| `intel quota` | None | `/intel/quota` |
| `intel <ip\|asn\|cidr\|ja3\|ja4> <query>` | None | `/intel/lookup?q=…&type=…` |
| `settings lifecycle-emails` | None | `/settings/lifecycle-emails` |
| `settings broadcast-emails` | None | `/settings/broadcast-emails` |
| `settings applications` | None | `/integrations/grants` |

Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Personal settings and `notifications preferences` belong to each user: with `--customer-id` (View-as), a refusal prints `You don't have access to this.` with the hint `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` Reports are fetched on demand; this CLI does not persist report or billing records.

## Limits and pagination

These are CLI validation bounds; the service can impose stricter limits.

| Operation | Default `--limit` | Allowed range | Continuation |
|---|---:|---:|---|
| Incidents list | 50 | 1–100 | `--offset`; `has_more`, `filters_applied` preserved |
| Timeline | 100 | 1–200 | `--before` using `next_cursor` |
| Logs | 100 | 1–1000 | `--cursor` using `nextCursor` |
| Audit | 50 | 1–100 | `--cursor` using `next_cursor` |
| Reports list | 50 | 1–100 | `--offset` |
| Alerts list | 100 | 1–100 | Bounded list; use `--start` and `--asset-id` to narrow |
| Notifications list | 100 | 1–100 | Bounded list |
| Provider events | 200 | 1–500 | Bounded sample; aggregates remain server-provided |
| Asset/incident graph | 200 | 1–1000 | Bounded graph |

Offsets are integers 0–1,000,000 and are omitted unless supplied. Graph minimum weight defaults to 1 and accepts integers 1–1,000,000. Graph hours default to 24 and accept 1–720. No command auto-fetches unbounded pages.

Examples:

```bash
vigilbase security incidents --status open --severity high
vigilbase security incidents timeline <incident-uuid> --before '<cursor>'
vigilbase security incidents update <incident-uuid> acknowledged --note 'Review started' --confirm
vigilbase security assets graph <asset-uuid> --dataset http_requests --hours 24 --json
vigilbase security analytics security-analysis --asset-id <asset-uuid> --hours 48
vigilbase security zero-trust gateway dns --hours 24 --json
vigilbase security cloudflare-account posture --customer-id <one-customer-uuid>
vigilbase security connections logpush-status <connection-uuid> <job-uuid>
vigilbase security intel ip 1.1.1.1
```

Binary log downloads and routes without a verified JSON consumer are not exposed.