Home / Documentation

Documentation

Everything we have written down.

The index below is the whole set. Where a page describes something that has not shipped, it says so and gives the date it publishes. The full reference and the API browser live in the console.

1 · Install the agent

There are three ways to run it: a Linux binary, a macOS binary and a Docker image. The page covers all three with the same enrolment flow.

docker run -d --restart unless-stopped \
  -e CYBERLOP_ENROLL_TOKEN=<single-use-token> \
  -e CYBERLOP_URL=https://app.cyberlop.com \
  --name cyberlop-agent \
  ghcr.io/cyberlop-labs/agent:latest

Create the agent in Settings, copy the single-use enrolment token, and run it wherever it can reach your application and your repository. It exchanges the token for a durable key on first contact and then polls for work. It opens no inbound ports. Assign it to a scan profile and every scan on that profile runs inside your network.

2 · Register an application

An application is one deployed thing. We need to reach it, and we need the code behind it.

Frontend URL: where the application actually runs. Staging is usually the right choice for a first run with exploitation enabled.
Repository URL and branch: cloned at launch over HTTPS. Private repositories use a scoped token you supply once.
Environment and owning team: used for filtering and for routing work to the right people.

On the hosted platform an application must have a repository URL. Local filesystem paths are disabled by design.

3 · Roles and credentials

This is the step people skip, and it is the one that unlocks the most valuable findings. Add one credential per role, each with a name and a privilege level.

Viewer     privilege 1    viewer@example.com
Support    privilege 2    support@example.com
Manager    privilege 3    manager@example.com
Admin      privilege 4    admin@example.com

Credentials are encrypted with AES-256-GCM at rest, or resolved live from Azure Key Vault at launch so nothing sensitive persists here at all. They are masked in the interface and never written to logs or reports. The page also covers rotating a set and what happens to a scan mid-flight when you do.

4 · Read the matrix

Roles down the side, the doors they tried across the top. Green means locked. Pink means someone got in who shouldn't have, and the cell carries the request that did it.

With fewer than two roles the matrix cannot run, because there is nothing to compare. With four roles you get a sixteen-combination sweep on every scan. The page explains how to read a partial result when a login fails mid-scan, and what an informational cell means.

Confirmed-only

Reporting that includes only what was exploited, with the proof files exported as a bundle. Ships 19 October, and the page publishes with it. Today a profile filters on minimum severity and confidence, which is documented under scan profiles, and the report tells you plainly which findings were confirmed and which were not.

Prove the fix

Today: fix something, then run Retest. It replays only the previously confirmed exploits and closes the ones that now fail. That is documented and working.

The full prove-the-fix record keeps the original exploit, the change, and the re-exploit that failed together as one artefact. It lands 16 November, and the page publishes with it.

CI gate setup

Two endpoints: start a scan, then poll the gate. Fail the build when the gate does not pass. The GitHub Action template is written up today; the GitLab version of the page publishes with the GitLab template on 25 November.

SCAN=$(curl -sf -X POST "$CYBERLOP_URL/api/ci/scan" \
  -H "authorization: Bearer $CYBERLOP_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"profileName":"nightly-full","commitSha":"'"$GIT_SHA"'"}' | jq -r .scanId)

curl -sf "$CYBERLOP_URL/api/ci/gate/$SCAN" \
  -H "authorization: Bearer $CYBERLOP_TOKEN" | jq -e '.pass'

The gate compares against the previous scan of the same application, so it fails on new criticals rather than on the standing backlog.

White-label

Putting your own name and logo on a report, for firms who deliver testing to their own clients. Branded HTML and PDF reports with secret redaction work today. The partner tenant model and white-label reporting land 30 October, the multi-client console 27 November, and the page publishes with them. Commercial terms are on the partner page.

API reference

Everything the console does is available to a scoped API token. Create tokens under Account.

GET    /api/targets                 list applications
POST   /api/targets                 register an application
GET    /api/profiles?targetId=      profiles for an application
POST   /api/scans                   launch a scan
GET    /api/scans/:id               status, metrics, cost
GET    /api/scans/:id/log           live log tail
POST   /api/scans/:id/cancel        stop a running scan
GET    /api/issues?scanId=          findings for a scan
PATCH  /api/issues/:id              triage: status, assignee, notes
GET    /api/diff/:scanId            new / fixed / regressed
GET    /api/scans/:id/report.pdf    branded PDF report
POST   /api/ci/scan                 pipeline entry point
GET    /api/ci/gate/:scanId         build gate verdict

Authenticate with authorization: Bearer <token>. All responses are JSON. Rate limits apply per token.

Not written yet

There is no page on issue-tracker sync, single sign-on beyond Okta, self-serve signup, data residency or air-gapped deployment, because none of those exist. What that means in practice is on the integrations page.

Configure it

A profile, a pipeline step, an API call.

Scan configuration is a saved profile you reuse, and everything the console does is available to a token. Application context is the field most people skip and the one that most improves business-logic results.

＃ what to test, and how far to go
vuln_classes: [authz, business-logic, injection, secrets]
exploit: true
report:
  min_severity: medium
  min_confidence: high

＃ one credential per role: this is what
＃ makes the authorization matrix possible
roles:
  - { name: viewer,  privilege: 1 }
  - { name: support, privilege: 2 }
  - { name: manager, privilege: 3 }
  - { name: admin,   privilege: 4 }

context:
  what_it_does: "B2B invoicing and payouts"
  crown_jewels: ["customer PII", "payout rails"]

＃ scan on merge, fail the build on new criticals
- name: Cyberlop scan
  run: |
    SCAN=$(curl -sf -X POST "$CYBERLOP_URL/api/ci/scan" \
      -H "authorization: Bearer $CYBERLOP_TOKEN" \
      -H 'content-type: application/json' \
      -d '{"profileName":"nightly-full",
           "commitSha":"'"$GIT_SHA"'"}' | jq -r .scanId)

    curl -sf "$CYBERLOP_URL/api/ci/gate/$SCAN" \
      -H "authorization: Bearer $CYBERLOP_TOKEN" \
      | jq -e '.pass'

＃ the gate compares against the previous scan of the
＃ same application, so it fires on NEW criticals only

＃ everything the console does, available to a token
POST   /api/scans                 launch a scan
GET    /api/scans/:id             status, metrics, cost
GET    /api/scans/:id/log         live log tail
GET    /api/issues?scanId=        findings
PATCH  /api/issues/:id            triage
GET    /api/diff/:scanId          new / fixed / regressed
GET    /api/scans/:id/report.pdf  branded report

＃ launch a retest, replaying only what was confirmed
$ curl -X POST "$URL/api/scans" \
    -H "authorization: Bearer $TOKEN" \
    -d '{"profileId":"...","retest":true}'

← { "scanId": "4f2a91", "replaying": 3 }

Read it, then run it on one app.

If one of those pages left you with a question, the fastest answer is someone sharing a screen. We will run the install, the credentials step and the matrix live, in that order, and you can stop us on any line.

Book a demo → How it works

Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.

Platform

Solutions

Learn

Resources

Company