Concepts

The mental model behind Cybros. Once these nouns click, the API, CLI, and SDKs all read the same way.

Org ─┬─ Projects ─── Repositories
     │                    │
     │                    ▼
     │                  Scan ──── Findings ──┬── AI analysis (9 agents)
     │                    │                  └── Remediation (6-step → PR)
     │                    ▼
     │               Compliance (frameworks × controls)
     │
     ├─ API keys        ├─ Members / roles (RBAC)
     └─ Credits ledger  └─ Audit log

Organization

The top-level tenant. Everything — repositories, scans, findings, keys, credits, members — belongs to an org. Your API key is scoped to one org; client.me() tells you which one is active (active_org_id) and your role in it.

Project & Repository

A repository is a connected source repo (GitHub today). Repositories are grouped into projects for organization and access control. A repository has a full_name (owner/repo), a default_branch, and a detected primary_language.

The CLI resolves the current git remote to a repository automatically; you can also target one by id with --repo.

Scan

A scan is one security assessment of a repository at a git ref. Creating a scan (POST /scans) runs a set of modules (SAST, secrets, SCA, IaC, …) and optionally assesses compliance frameworks. Scans are incremental by default — only changed files and their blast radius are analyzed unless you request a full scan.

A scan moves through statuses and ends in a terminal state:

queued → running → completed | failed | cancelled

Each scan reports a per-module breakdown, a findings_summary by severity, and credits_spent. Its report (GET /scans/{id}/report) adds a risk_score and severity breakdown.

Finding

A finding is one issue a scan produced: a severity, a rule_id, a title, a file_path:line, and enrichment (OWASP, CWE, CVSS). Findings have a lifecycle status (open, …).

A finding's detail (GET /findings/{id}) is the security workspace view: the evidence snippet, business impact, an AI explanation, and a suggested fix (remediation text + a unified diff when a patch is available).

AI analysis (9 agents)

Beyond deterministic scanners, Cybros runs a 9-agent AI analysis over a scan's findings (POST /scans/{id}/ai-analysis). Each agent has a sequence, runs in order, and reports a status and confidence. The analysis rolls up to an overall_confidence, a risk_score, and a summary. Agents can also produce fix patches (GET /scans/{id}/ai-analysis/patches).

The agents triage false positives, explain impact in plain language, map to standards, and draft fixes — turning raw scanner output into trustworthy, actionable findings.

Remediation (6-step pipeline)

Remediation turns a finding into a pull request (POST /findings/{id}/remediate). The job runs a 6-step pipeline — each step reports a status and detail — and, on success, returns a pr_url and branch. It validates the fix (tests + a re-scan of the patch) before opening the PR, so you review a green, already-checked change.

Compliance

Cybros maps findings onto compliance frameworks (SOC 2, ISO 27001, …). The overview (GET /compliance/overview) gives a per-framework and overall score as a percentage. A framework's detail breaks the score down into individual controls, each with a pass/fail status and the findings that violate it. Scores are live — they move as you fix findings, and can be scoped to a specific scan.

AI security posture

A dedicated view of AI/LLM-specific risk (GET /ai-security/overview): checks mapped to the OWASP LLM Top 10, whether an AI stack was detected in the repo, and how many checks passed vs. failed. Surfaced in the CLI by cybros audit.

Policies & the deployment gate

Findings and scores feed policies — e.g. "block deploys on critical/high findings." The deployment gate endpoint evaluates a commit against policy and returns an approved boolean your CI can enforce.

Supporting objects

Credits

Scans and AI analyses consume credits, tracked in an append-only ledger (balances are derived, never mutated). Each scan/analysis reports its credits_spent; usage is queryable via client.billing.usage().

API keys & roles

API keys authenticate programmatic access; org members authenticate as themselves. Both carry a role that bounds permissions (client.me().permissions).

Audit log

Every meaningful action (scans, key changes, remediations, …) is recorded in an audit log — an immutable, queryable trail (client.audit.list(...)).

How the surfaces map to these nouns

Next: the CLI reference or the Python / TypeScript SDK.