Docs/Get started/Quickstart

Quickstart.

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

Time ≈ 15 minutesNeeds org admin or scan:createUpdated September 2026

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

2. Install and log in with the CLI

pip install esos-cli          # or: pipx install esos-cli
esos auth login               # OAuth 2.0 device flow; --api-key for CI
esos auth status

Configuration is written to ~/.esos/config.yaml (api_url, api_key, org_id, default_severity) with owner-only file permissions.

3. Connect a repository

Under Integrations → Source control connect GitHub, GitLab, Bitbucket or Azure DevOps. The connector registers repositories, receives webhooks for pushes and pull requests, and posts gate results and comments back. Alternatively scan any reachable Git URL directly from the CLI.

4. Run a scan

esos scan repo .                          # current directory
esos scan run --target https://github.com/org/app --type sast
esos scan image ghcr.io/org/app:1.4.2
esos scan url https://staging.example.com --profile passive
esos scan api ./openapi.yaml

For a repository the orchestrator launches the native engine (appsec-unified), semgrep, gitleaks, architecture, checkov, syft and grype, plus the language-specific tools 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, cppcheck for C/C++. Each tool has its own deadline; a slow tool yields a PARTIAL scan, never a hung one.

5. Gate a pipeline

esos --fail-on critical ci scan --output sarif > results.sarif   # exit 1 on breach
esos findings list --severity high --output junit > findings.xml

Exit codes: 0 success, 1 policy failure (threshold or deny), 2 API / network / auth error. SARIF output uploads to GitHub code scanning; JUnit output renders in Jenkins and GitLab.

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, inferred); a missing hop names the 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 the runtime side.

Where to next

Core concepts — how observations become findings, cases, attack paths and risk.
Policy authoring — turn a threshold into a Rego policy with a signed decision.
Run scanners in your own cluster — register an execution cluster so code never leaves your environment.