Git Sync

When using the Detection Rules as Code feature, you can use the API to drive detection rule syncs from your own tooling — either to trigger a GitHub-polled sync immediately (e.g. on commit) or to push a repository / individual rule to a user-pushed sync source.

Trigger a GitHub-polled sync

POST /v1/sync_github_repositories

Trigger an immediate sync for the tenant's GitHub-polled sync sources. Syncs run automatically every 5 minutes; use this endpoint to sync sooner (e.g. immediately after a commit lands).

Body

Name	Type	Description
tenant_id required	string	Unique identifier for the tenant

Example

curl $API_BASE/v1/sync_github_repositories \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "tenant_id": "00000000-0000-0000-0000-000000000000" }'

Response

Returns the tenant_id.

{ "tenant_id": "00000000-0000-0000-0000-000000000000" }

Upload a repository zipball

POST /v1/upload_git_repo_zipball

Upload a zip archive of a repository to a user-pushed sync source. The server runs the same validate / test / materialize pipeline as a GitHub-polled sync, so a successful upload fully reconciles the sync source against the contents of the zip (including deleting rules whose YAML has been removed).

This is the endpoint scanner-cli sync-git-repo calls. Most users should use the CLI (or the scanner-inc/sync-detection-rules GitHub Action that wraps it) rather than hitting the endpoint directly — the CLI handles zipping the working tree, deriving the branch / commit SHA / commit message, and surfacing per-file failures for you.

Body

multipart/form-data with the following fields:

Name	Type	Description
push_key required	string	Per-tenant identifier of the push sync source. Set by you when you add a push sync source under Detections > Synced Repositories.
branch required	string	Branch the uploaded zip corresponds to. (push_key, branch) picks exactly one sync source row.
commit_sha required	string	Arbitrary revision identifier (typically git rev-parse HEAD, optionally with a +dirty suffix). Stored verbatim on the resulting sync attempt.
commit_message	string	Optional commit message to store alongside the SHA, e.g. the first line of git log -1 --pretty=%B. Absent or empty falls back to a synthetic pushed at <ts> placeholder.
zip required	file (binary)	Raw zip archive of the repository at the specified revision, in the same layout that GitHub's zipball archive endpoint produces.

Example

curl "$API_BASE/v1/upload_git_repo_zipball" \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-X POST \
-F "push_key=my-rules-repo" \
-F "branch=main" \
-F "commit_sha=$(git rev-parse HEAD)" \
-F "commit_message=$(git log -1 --pretty=%B)" \
-F "zip=@repo.zip;type=application/zip"

Response

Returns counts of rules synced, failures, and warnings. If failures is non-empty, no rules from the upload were synced (detection_rules_synced and detection_rules_deleted are both 0).

{
  "detection_rules_synced": 12,
  "detection_rules_deleted": 1,
  "failures": [],
  "warnings": []
}

Upsert a single rule by push key

POST /v1/detection_rule_yaml/upsert_by_push_key

Create or update a single detection rule on a user-pushed sync source, keyed by the push_key (or legacy sync_key) declared in the rule's YAML.

This is the endpoint scanner-cli sync calls per file. Most users should use the CLI rather than hitting the endpoint directly.

For normal flows, prefer /v1/upload_git_repo_zipball (or GitHub-polled sync): both reconcile the whole set of rules in a sync source on every run. This endpoint only creates and updates rules — it has no way to delete a rule that's been removed from the repo — and shouldn't be mixed with the repo-level flows on the same rules.

Body

Name	Type	Description
rule_yaml required	string	Single detection rule YAML. Must declare a push_key (or legacy sync_key) at the top level; that key identifies the rule within its tenant for upsert lookup. See the detection rule schema.
sync_config_yaml required	string	Per-repo sync config YAML providing the event_sink_keys → event_sink_ids map used to resolve the rule's event_sink_keys. Pass an empty string ("") or a YAML doc with no event_sink_keys field if the rule has no event sinks.

Example

curl $API_BASE/v1/detection_rule_yaml/upsert_by_push_key \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
    "rule_yaml": "# schema: https://scanner.dev/schema/scanner-detection-rule.v1.json\nname: ...\npush_key: my-rule\n...",
    "sync_config_yaml": "event_sink_keys:\n  low_severity_alerts:\n    - sink_id: \"00000000-0000-0000-0000-000000000000\"\n"
}'

Response

Returns the upserted detection rule and whether it was newly created.

{
  "detection_rule": {
    "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
    "...": "..."
  },
  "created": true
}