Authentication

The CLI authenticates through your browser: you sign in on the AlertaVuln web app, and a session token is handed back to the CLI over a one-time localhost callback. No credentials are ever typed into the terminal.

How av login works

av login

1. The CLI starts a one-time HTTP listener on a random 127.0.0.1 port and generates a random state value to protect the callback against CSRF.

2. Your browser opens at the AlertaVuln sign-in page, carrying the callback port and state. If the browser can’t be opened automatically, the URL is printed so you can visit it by hand.

3. You authenticate on the web - Entra/Microsoft, Google, or email.

4. The browser hands the session token back to the CLI over the localhost callback. The CLI verifies the state value, saves the token, and prints Logged in as <email>.

av login waits up to three minutes for the browser sign-in to complete (Ctrl-C to abort), then times out.

Note

The callback listener binds 127.0.0.1 on the machine running av login, so the browser must run on that same machine (or have its traffic forwarded to it, e.g. over SSH port forwarding).

Check your session at any time:

av whoami

av whoami prints the signed-in email and the API URL the CLI resolved for this invocation. av logout clears the stored token and email.

Two-factor authentication

When two-factor authentication is turned on for your account (Settings, Security), signing in on the web asks for a code from your authenticator app after your password or single sign-on. After a successful code, including the one you enter to turn two-factor authentication on, that browser is trusted for 3 hours: signing in again from it within that time skips the code. That covers an av login that opens it, signing in again after switching organisation, and accepting an invitation to another organisation. Signing out does not end the window. Signing in from another browser or computer still asks for a code, and disabling two-factor authentication ends the trust immediately, so enrolling again later means every other browser is asked for a code once more.

Where the token lives

The token is cached in config.json under your platform’s user config directory:

Platform	Path
Linux	$XDG_CONFIG_HOME/alertavuln/config.json (defaults to ~/.config/alertavuln/config.json)
macOS	~/Library/Application Support/alertavuln/config.json
Windows	%AppData%\alertavuln\config.json

The file stores only the token and your email, and is written with owner-only permissions (0600, directory 0700) on Unix-like systems.

Caution

The token is a bearer credential for your AlertaVuln account - treat config.json like a password. Run av logout on machines you’re done with.

Commands that talk to the API require a token and fail with not logged in - run 'alertavuln login' first when none is stored. The one notable exception: a local av sast scan runs without any login, as long as you don’t upload results with --project.

How the CLI resolves the API URL

Every invocation resolves the API base URL fresh, in this order:

Precedence	Source	Scope
1	--api-url flag	this invocation only
2	ALERTAVULN_API_URL environment variable	current shell / CI job
3	Default: https://alertavuln.com	-

--api-url is a global flag, available on every command:

av --api-url https://your-instance.example.com login

Note

The API URL is deliberately never persisted to config.json. An api_url key left in the file by an older CLI version is ignored: the CLI always starts from the production default and applies only per-invocation overrides, so a one-off run against another instance can’t silently stick for every later command.

See also

• Quickstart - install, sign in, and get your first verdict.
• av login - command reference.
• Install the CLI - installers, checksums, and versions.