Skip to main content

Cloud (CSPM) — Running scans via the API

This is the API-level walkthrough of the CSPM lifecycle: connect → validate → scan → track. It uses the same authenticated /api/v1 API as every module (see Platform API for the auth model). For the customer-side role setup that sits between connect and validate, see Connecting AWS.

All calls below are under /api/v1/org and send the three keys (X-Master-Key, X-Admin-Key, X-Org-Key). $BASE is your deployment, e.g. https://modules.binarynetworks.ai/api/v1. The cloud provider path segment is aws (the module key).

:::note Same API for Azure and GCP The examples below use aws. Azure and GCP are identical — substitute the provider in the path (/org/azure/..., /org/gcp/...) and in {"module": "azure"} / {"module": "gcp"}. The only difference is the connect payload (the read-only credential each provider needs): see Connecting Azure and Connecting GCP. :::

1. Connect an account​

POST /org/aws/accounts — registers the account and mints an External ID. The response includes the External ID and the assumer identity to put in your read-only role's trust policy. No secrets are accepted or stored; status starts pending.

curl -X POST "$BASE/org/aws/accounts" \
  -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG" \
  -H "Content-Type: application/json" \
  -d '{"provider":"aws","account_id":"123456789012","display_name":"Production"}'
{
  "id": "…", "provider": "aws", "account_id": "123456789012",
  "display_name": "Production", "role_arn": null, "assumer_role_arn": "…",
  "external_id": "…", "status": "pending", "last_validated_at": null,
  "attributes": {}, "created_at": "…"
}

Returns 403 if the aws module is not enabled for the org.

2. Create the read-only role, then attach its ARN​

Using the External ID and assumer identity from step 1, deploy the read-only role in your AWS account (CloudFormation for one account, or a StackSet for an Organization) — see Connecting AWS. Then attach the resulting role ARN by re-connecting the same account (it updates in place and returns to pending for re-validation):

curl -X POST "$BASE/org/aws/accounts" \
  -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG" \
  -H "Content-Type: application/json" \
  -d '{"provider":"aws","account_id":"123456789012",
       "role_arn":"arn:aws:iam::123456789012:role/your-readonly-role"}'

3. Validate access​

POST /org/aws/accounts/{account_id}/validate — does a live test AssumeRole right now (delegated to the cloud-worker, which holds the cloud identity). On success the account becomes validated (scans allowed); on failure it becomes invalid with the reason, so you can fix the trust policy or External ID immediately.

curl -X POST "$BASE/org/aws/accounts/$ACCOUNT_UUID/validate" \
  -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG"

4. Check the gate​

GET /org/aws/status — whether a cloud scan can run (module enabled and ≥1 validated account):

curl "$BASE/org/aws/status" \
  -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG"
# {"module":"aws","enabled":true,"validated_accounts":1,"can_run":true}

Other account operations: GET /org/aws/accounts (list connected accounts), DELETE /org/aws/accounts/{account_id} (disconnect — removes stored config).

5. Run the scan​

POST /org/scans with {"module":"aws"} — starts a CSPM scan across all validated AWS accounts. Returns 202 Accepted with the scan job.

curl -X POST "$BASE/org/scans" \
  -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG" \
  -H "Content-Type: application/json" \
  -d '{"module":"aws"}'
  • 409 Conflict — "AWS requires a validated cloud account. Connect one first." (no validated account yet).
  • 403 Forbidden — the aws module is not enabled for the org.
  • Subject to the per-(org, module) cooldown (default 14 days); failed or cancelled scans don't burn the slot.

6. Track progress​

The cloud-worker wakes from zero (cold start ~1–3 min is normal), assumes each account, runs the scan to completion, and writes results to the org schema.

curl "$BASE/org/scans/$SCAN_ID"          -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG"
curl "$BASE/org/scans/$SCAN_ID/progress" -H "X-Master-Key: $MASTER" -H "X-Admin-Key: $ADMIN" -H "X-Org-Key: $ORG"

When it completes, read the posture and findings — see Findings & compliance.