Identity Watchlist Definitions
Manage stored signing-identity definitions and test sample identities against them. Definitions and pattern tests do not establish active monitoring or alert history.
Owner contracts were source-reviewed against 14b4a77263 on 2026-10-07. CLI builds carrying PCD-449 use those contracts through the configured backend. Re-verify the registered command with pwsh tools/scripts/test-targeted-xunit.ps1 -Project src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -Class '*WatchlistOwnerRouteTests' -BuildProjectReferences; verify the composed owner with the WatchlistOwnerHttpContractTests class in the Evidence WebService test project. These checks do not verify an installed CLI image, gateway or production database.
Supported operations
Evidence owns the definitions under /api/evidence/v1/watchlist.
| CLI operation | Owner request | Requested authority |
|---|---|---|
watchlist add | POST /api/evidence/v1/watchlist | trust:write; the owner accepts a global definition only from administrative authority (trust:admin, watchlist:admin or the admin role) and otherwise returns 403. The stellaops-cli client cannot hold trust:admin, so the CLI does not request it |
watchlist list | GET /api/evidence/v1/watchlist?includeGlobal=true | trust:read |
watchlist get | GET /api/evidence/v1/watchlist/{id} | trust:read |
watchlist update | Read the definition, then PUT /api/evidence/v1/watchlist/{id} | trust:write |
watchlist remove | DELETE /api/evidence/v1/watchlist/{id} | trust:write; the owner additionally requires administrative authority for global definitions and refuses system deletion |
watchlist test | POST /api/evidence/v1/watchlist/{id}/test | trust:read |
Configure the CLI backend and operator credentials first. Requests carry bearer authorization and the resolved tenant header; Evidence enforces token authority and tenant visibility. Definition reads may include global and system definitions. System definitions remain protected by the owner’s lifecycle rules.
Supply at least one identity dimension: issuer, subject alternative name (--san), or key ID. Match modes are exact, prefix, glob, and regex. The owner validates patterns, including regex safety. Severity, enabled state, suppression window, tags, and channel overrides are stored definition metadata. Changing them does not activate a monitoring service.
CLI examples
Create and list definitions:
stella watchlist add --issuer "https://token.actions.githubusercontent.com" --name "GitHub Actions" --format json
stella watchlist add --san "*@example.com" --match-mode glob --name "Example identity" --format json
stella watchlist list --include-global --format json
Use the returned GUID for detail, update, pattern test, and deletion:
stella watchlist get <entry-id> --format json
stella watchlist update <entry-id> --enabled false --format json
stella watchlist test <entry-id> --issuer "https://token.actions.githubusercontent.com" --format json
stella watchlist remove <entry-id>
Updates preserve existing identity fields, scope, tags, and channel overrides. The existing --suppress-duplicates option sets suppression-window metadata, and -s remains the severity alias. List options --severity and --enabled-only filter definitions actually returned by the owner. Deletion requires confirmation unless --force is supplied. JSON output contains the owner data without progress or success text. The pattern response preserves the owner’s numeric matched-field flags; a match describes the supplied sample, not an observed event.
Results and failures
| Outcome | CLI exit | Meaning |
|---|---|---|
| Owner success, including a genuine empty definition list | 0 | The configured owner completed the operation |
Invalid arguments or owner pattern validation (400) | 2 | Correct the input |
Missing backend/credentials, offline mode, transport failure or unavailable owner (503) | 3 | No successful owner result was obtained |
Denied authority (401 or 403) | 6 | The caller lacks the required authority |
Missing or tenant-hidden definition (404) | 7 | The owner did not expose the requested definition |
| Malformed owner response or another owner failure | 8 | No valid successful result was obtained |
Failures emit diagnostics on stderr and no definition or match result on stdout. Raw credential-bearing exceptions and problem bodies are not printed. No predecessor-route retry or local sample data supplies a result.
Monitoring boundary
The CLI has no alert-history subcommand, and Evidence maps no alert-history route: CCP-036 withdrew the former handler, which returned fixed empty data, so GET /api/evidence/v1/watchlist/alerts now returns 404. The current Evidence composition does not register the background monitor and uses disabled event-source and alert-publication adapters. The Console Watchlist page states that alert history and active monitoring are unavailable and shows no alert counts. Stored suppression metadata and deduplication rows are not an alert-history store.
Durable monitoring and history remain separate work. Use the monitoring runbook for its explicit implementation limits, and the Evidence architecture for ownership. Do not use monitoring counters, notification examples, or dated pipeline designs as current acceptance evidence.