Documentation
Credential methods, storage backends, precedence, file permissions, and rotation for the Vulnetix CLI and Package Firewall.
Every Vulnetix product authenticates against a single organization identity. This section covers how to obtain credentials, where to put them, how the CLI decides which one to use, and how to store them safely on developer machines, in containers, and in CI.
Short answer for most people:
vulnetix auth login --store keyring
Browser device flow, secret held in the OS keychain, nothing sensitive on disk. Everything below is detail for the cases where that is not possible.
| Method | Flag | Environment | Requires --org-id | Header sent |
|---|---|---|---|---|
| Bearer token | --token | VULNETIX_API_TOKEN | No — org resolved server-side | Authorization: Bearer <token> |
| ApiKey | --api-key | VULNETIX_API_KEY + VULNETIX_ORG_ID | Yes | Authorization: ApiKey <org>:<key> |
| SigV4 | --secret | VVD_ORG + VVD_SECRET | Yes | Authorization: ApiKey <org>:<hmac> (derived) |
--api-key, --secret, and --token are mutually exclusive. Passing more than one fails with choose only one of --api-key, --secret, or --token.
--secret is not an alias for --api-key. It takes the SigV4 HMAC secret, from which the CLI derives HMAC-SHA256(secret, orgID). Passing an ApiKey to --secret produces a wrong signature and the login fails.| Backend | Location | Secret at rest |
|---|---|---|
| Keyring (recommended) | OS keychain + metadata in ~/.vulnetix/credentials.json | OS keychain |
| Home file | ~/.vulnetix/credentials.json | Plaintext JSON, mode 0600 |
| Project file | ./.vulnetix/credentials.json | Plaintext JSON, mode 0600 |
| netrc | ~/.netrc (~/_netrc on Windows) | Plaintext, mode 0600 enforced |
Environment variables are a fifth source — they persist nothing and take precedence over all files.
| Command | Purpose |
|---|---|
vulnetix auth / vulnetix auth login | Authenticate. Browser device flow by default. |
vulnetix auth status | Show the active credential, its source, your plan, and the state of every credential source. |
vulnetix auth verify | Validate credentials against the API without saving or modifying anything. Designed for CI. |
vulnetix auth logout | Remove credentials from both file stores and clear the matching OS keychain entries. |
vulnetix auth verify never writes. Use it as the first step of any pipeline that assumes credentials are present.
The CLI ships with an embedded community organization credential. When no credential is found, VDB lookups still work at community rate limits — vulnetix auth status reports Community - unauthenticated (VDB only).
The embedded credential is intentionally public. It traverses the identical API gateway, auth headers, and rate-limit enforcement as any registered user, so it grants no privilege a stranger could not obtain by signing up. Uploads, org-scoped data, and enterprise features require a real credential.