arbiter-script

name	arbiter-script
description	Create, review, and validate GuanceCloud Arbiter scripts for security detection rules. Use when Codex needs to author SIEM or CSPM detection logic, query data with dql or PromQL, process DQL series, call trigger to generate security events, inspect Arbiter built-in functions, or debug Arbiter syntax/runtime/trigger-output problems.

Arbiter Script

Workflow

1. Classify the rule before writing code:
   • SIEM: runtime activity detection from logs, events, metrics, traces, network, or cloud audit data.
   • CSPM: static cloud/resource configuration posture checks, baseline drift, and compliance gaps.
2. Define the detection contract: data source and DQL/PromQL query, time range, grouping dimensions, trigger condition, severity, dimension tags, related data, and optional target workspace.
   • For dql() query authoring, repairing, or final delivery, also use the local dql skill workflow. Do not use a generic SQL skill to generate DQL; DQL has different grammar and must pass dqlcheck.
3. Query function docs before guessing syntax:

./bin/arbiter-check --search-functions dql --function-lang all
./bin/arbiter-check --function-doc trigger

4. For any final executable DQL, follow the dql skill rules. Run ../dql/bin/dqldocs once before reading DQL references, and validate each DQL with ../dql/bin/dqlcheck or ./bin/arbiter-check --check-dql.
5. Write scripts in Platypus syntax. Use dql() to fetch data, dql_series_get() for common column/tag extraction, explicit loops when row-level context matters, and trigger() only when the condition is met.
   • Alias every DQL expression to the exact simple field name read by dql_series_get(). Do not read accountId if the DQL aliases the field as userId.
   • Validate both positive and negative branches with mock DQL results when status/severity depends on an extracted value.
6. Keep dimension_tags small and stable. Put high-cardinality evidence such as IPs, user IDs, resource IDs, request IDs, matched rows, and raw query details into related_data.
7. Validate with the skill-local checker. Use mock DQL for script logic and trigger payload tests:

./bin/arbiter-check \
  --script ./rule.p \
  --dql-result-file ./sample-dql-result.json \
  --check-dql \
  --require-trigger \
  --expect-status high

When OpenAPI credentials are available and the task requires real DQL verification, run live DQL:

./bin/arbiter-check \
  --script ./rule.p \
  --live-dql \
  --guance https://openapi.guance.com \
  --guance-key "$GUANCE_API_KEY" \
  --check-dql \
  --duration 15m

For syntax-only checks:

./bin/arbiter-check --script ./rule.p --parse-only

8. If validation fails, fix DQL check failures first, then parse/type/runtime errors, then trigger assertions. Verify dql_checks, dql_mode, dql_queries, stdout, and triggers in the JSON output. Do not claim DQL is executable unless every dql_checks[].ok is true or each query passed dqlcheck individually. Do not claim DQL is verified against real data unless dql_mode is live and ./bin/arbiter-check exits successfully.
9. Report the final script, the validation command, and the important execution output: dql_checks, triggers, dql_queries, stdout, and any errors.

References

Read security-overview.md when deciding SIEM versus CSPM behavior, event lifecycle, severity, or signal/event handling.

Read arbiter-patterns.md when writing detection scripts, choosing dql_series_get() versus loops, building trigger payloads, or preparing mock DQL results.

Read cloud-security-patterns.md when writing cloud audit rules such as AWS CloudTrail, root account activity, IAM changes, console login, cloud posture, or account/resource evidence.

Read troubleshooting.md when the checker reports parse errors, missing DQL context, no trigger output, unexpected status, or DQL result shape issues.