Quickstart.

From sign-in to a finding with lineage. No scanner configuration file is needed: the tool plan is derived from the repository.

Before you start

• A SecurityVault account with the organisation admin role or the scan:create permission.
• Python 3.11 or later on the machine where you install the CLI.
• A Git repository reachable from the platform, on GitHub, GitLab, Bitbucket or Azure DevOps.

1. Sign in

Open app.securityvault.io. Single sign-on (OIDC or SAML) is configured per organisation, and MFA is available. Inbound SCIM provisioning is in development. Your organisation id is shown under Settings → Organisation; API calls send it as the X-Organization-ID header.

2. Install and log in with the CLI

In the console, open Developer → Quickstart and choose Download esos-cli. Then install the wheel and log in:

python -m pip install --upgrade ./esos_cli-0.1.1-py3-none-any.whl
esos auth login               # OAuth 2.0 device flow; use --api-key in CI
esos config set org_id <your-organisation-id>
esos auth status

Settings (api_url, org_id, default_severity, fail_on) are written to ~/.esos/config.yaml with owner-only permissions. The token uses your operating system's keychain by default. See the CLI reference for the explicit plaintext fallback on runners without a keychain.

3. Connect a repository

Under Integrations → Source control, connect GitHub, GitLab, Bitbucket or Azure DevOps. The connector registers repositories, receives push and pull-request webhooks, and posts gate results and comments back. You can also scan any reachable Git URL directly from the CLI.

4. Run a scan

esos scan repo https://github.com/your-org/app       # a Git repository
esos scan image ghcr.io/your-org/app:1.4.2           # a container image
esos scan api ./openapi.yaml                          # an OpenAPI specification

For a repository, the platform runs its native engine alongside semgrep, gitleaks, checkov, syft and grype, plus language-specific tools for the languages it detects — for example bandit and pip-audit for Python, gosec and govulncheck for Go, spotbugs for Java, njsscan for JavaScript, brakeman for Ruby, cargo-audit for Rust and cppcheck for C/C++. If one tool cannot finish, the scan ends partial: results from the others are kept and the gap is shown.

5. Gate a pipeline

esos auth login --api-key "$ESOS_API_KEY"
esos ci scan --target https://github.com/your-org/app \
  --format sarif --output results.sarif --fail-on critical

Exit codes: 0 success, 1 policy failure (a finding at or above the --fail-on threshold), 2 API, network or authentication error. SARIF uploads to GitHub code scanning; --format junit renders in Jenkins and GitLab test reports.

6. Read the lineage

Open any finding and choose Lineage, or call GET /api/v2/findings/{id}/lineage. The view walks Repository → Commit → Build → ContainerImage → Registry → Workload → Service → Ingress. Every hop shows its provenance (observed, derived or inferred); a missing hop names its reason — no_producer_data, source_gap or unbound_endpoint — instead of pretending the chain is complete. Connect a registry and a cluster (Integrations → Registries, Integrations → Clusters, or the Kubernetes sensor chart) to fill in the runtime side.

Next steps

• Core concepts — how observations become findings, cases, attack paths and risk.
• Policy authoring — turn a threshold into a Rego policy with a signed decision.
• CLI reference — every command, option and exit code.
• Run the platform fully self-hosted, on request, with storage and outbound access controlled by your deployment configuration. Registering your own scan cluster while we host the platform is in development. Discuss rollout with our team.