brava-cli 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,51 @@
1
+ Metadata-Version: 2.5
2
+ Name: brava-cli
3
+ Version: 0.4.0
4
+ Summary: Brava Security CLI
5
+ Requires-Python: >=3.10
6
+ Requires-Dist: httpx>=0.28.0
7
+ Requires-Dist: python-dotenv>=1.0.0
8
+ Requires-Dist: rich>=13.0.0
9
+ Requires-Dist: typer>=0.15.0
10
+ Description-Content-Type: text/markdown
11
+
12
+ # Brava CLI
13
+
14
+ Command-line access to the [Brava Security](https://brava.security) platform for attack simulation and SIEM hygiene, built for terminals and CI.
15
+
16
+ ```bash
17
+ pip install brava-cli # or: uv tool install brava-cli
18
+ export BRAVA_URL=https://console.brava.security
19
+ export BRAVA_API_TOKEN=brava_… # API key from Settings → API Keys
20
+ brava doctor # shows which products your key can read
21
+ ```
22
+
23
+ Or store credentials once with `brava auth login --token <key>` (`--url` defaults to `https://console.brava.security`); `BRAVA_URL` / `BRAVA_API_TOKEN` override stored values.
24
+
25
+ | Product | API key scopes | Commands |
26
+ |---|---|---|
27
+ | Attack simulation | `simulations:run` | `brava catalog`, `brava run simulation`, `brava run goal` |
28
+ | Hygiene | `hygiene:read`, `hygiene:detections:test` | `brava siems list`, `brava run sweep`, `brava run test` |
29
+
30
+ With an API key, `brava run simulation|goal …` work when `--account-id` is the Brava environment UUID; `brava accounts list` and lookup by name or cloud account id are not available to API keys yet.
31
+
32
+ `brava doctor` marks a product NO ACCESS when the key lacks that product's read scope (`simulations:run`, `hygiene:read`); it exits `0` only when no check fails and at least one product is accessible (HTTP 200).
33
+
34
+ `brava run sweep watch` and `brava run test watch` exit `0` pass, `1` request, auth or validation error (e.g. a bad `--timeout`, missing URL/token), `2` gate failed (a hygiene check failed or a finding at/above `--fail-on`, default `high`) or a usage error caught while parsing arguments (e.g. `--fail-on bogus`, a missing run id), `3` timed out (run continues), `4` no answer (run FAILED/CANCELLED, verdict UNKNOWN, or an injection test (not a dry run) INCONCLUSIVE/NOT_TELEMETRY_DRIVEN). A sweep's log-type and feed warnings never change the exit code. `brava run test create --dry-run` runs the hygiene checks only and is judged like a sweep.
35
+
36
+ ## Check a rule before it is deployed (Google SecOps)
37
+
38
+ `brava run sweep create --siem <siem> --file rules/x.yaral` runs the hygiene checks on YARA-L rule text from a file instead of a live rule. Nothing is uploaded or changed in the SIEM: the text is compiled by Google SecOps' own compiler and checked as it will run once deployed (enabled and alerting). Text that doesn't compile always fails the run (exit `2`, whatever `--fail-on` is), with the compiler's messages in a `RULE_PARSE_ERROR` finding. `--file` alone treats the text as a new rule, so a live rule with the same name is reported as a duplicate; add `--rule <id|name>` when the text would replace that live rule, so the two aren't compared as duplicates (the live rule's enabled, alerting or archived state doesn't carry over). Pass `--rule`, `--file`, or both; neither, or a missing or empty file, is a usage error (exit `2`). If Brava can't reach the compiler the request fails (exit `1`).
39
+
40
+ The output says the run checked undeployed rule text, and the console is never refreshed for it (`consoleUpdate` is `null`). When `brava run test` could not inject telemetry for the rule, an informational line says why (`injectionBlocker` in `--json`: `NOT_TELEMETRY_DRIVEN` the rule reads no event data, `QUERY_UNPARSEABLE` the text could not be parsed for planning, `REFLIST_MEMBER_UNKNOWN` the rule is gated on a reference list with no readable entries); it never changes the exit code. Stale reference lists the rule reads are listed with the source warnings. Feed and log-volume warnings aren't shown for `--file`: they describe the SIEM, not the rule.
41
+
42
+ Data checks (log types receiving events, populated fields, parsers) run on the `--siem` SIEM. For a Dev SIEM that doesn't receive every source, set its **Fallback Telemetry Source** integration setting to the production SIEM: log types with no data in Dev are then measured there, read-only, and the Q1 detail names them. Without it, a rule reading a log type Dev doesn't receive fails Q1.
43
+
44
+ Pull-request pipeline (needs `jq`; `create --json` prints the run, including its `id`):
45
+
46
+ ```bash
47
+ id=$(brava run sweep create --siem "Google SecOps" --file rules/x.yaral --json | jq -r .id)
48
+ brava run sweep watch "$id" --fail-on high
49
+ ```
50
+
51
+ Documentation: https://docs.brava.security/cli/
@@ -0,0 +1,40 @@
1
+ # Brava CLI
2
+
3
+ Command-line access to the [Brava Security](https://brava.security) platform for attack simulation and SIEM hygiene, built for terminals and CI.
4
+
5
+ ```bash
6
+ pip install brava-cli # or: uv tool install brava-cli
7
+ export BRAVA_URL=https://console.brava.security
8
+ export BRAVA_API_TOKEN=brava_… # API key from Settings → API Keys
9
+ brava doctor # shows which products your key can read
10
+ ```
11
+
12
+ Or store credentials once with `brava auth login --token <key>` (`--url` defaults to `https://console.brava.security`); `BRAVA_URL` / `BRAVA_API_TOKEN` override stored values.
13
+
14
+ | Product | API key scopes | Commands |
15
+ |---|---|---|
16
+ | Attack simulation | `simulations:run` | `brava catalog`, `brava run simulation`, `brava run goal` |
17
+ | Hygiene | `hygiene:read`, `hygiene:detections:test` | `brava siems list`, `brava run sweep`, `brava run test` |
18
+
19
+ With an API key, `brava run simulation|goal …` work when `--account-id` is the Brava environment UUID; `brava accounts list` and lookup by name or cloud account id are not available to API keys yet.
20
+
21
+ `brava doctor` marks a product NO ACCESS when the key lacks that product's read scope (`simulations:run`, `hygiene:read`); it exits `0` only when no check fails and at least one product is accessible (HTTP 200).
22
+
23
+ `brava run sweep watch` and `brava run test watch` exit `0` pass, `1` request, auth or validation error (e.g. a bad `--timeout`, missing URL/token), `2` gate failed (a hygiene check failed or a finding at/above `--fail-on`, default `high`) or a usage error caught while parsing arguments (e.g. `--fail-on bogus`, a missing run id), `3` timed out (run continues), `4` no answer (run FAILED/CANCELLED, verdict UNKNOWN, or an injection test (not a dry run) INCONCLUSIVE/NOT_TELEMETRY_DRIVEN). A sweep's log-type and feed warnings never change the exit code. `brava run test create --dry-run` runs the hygiene checks only and is judged like a sweep.
24
+
25
+ ## Check a rule before it is deployed (Google SecOps)
26
+
27
+ `brava run sweep create --siem <siem> --file rules/x.yaral` runs the hygiene checks on YARA-L rule text from a file instead of a live rule. Nothing is uploaded or changed in the SIEM: the text is compiled by Google SecOps' own compiler and checked as it will run once deployed (enabled and alerting). Text that doesn't compile always fails the run (exit `2`, whatever `--fail-on` is), with the compiler's messages in a `RULE_PARSE_ERROR` finding. `--file` alone treats the text as a new rule, so a live rule with the same name is reported as a duplicate; add `--rule <id|name>` when the text would replace that live rule, so the two aren't compared as duplicates (the live rule's enabled, alerting or archived state doesn't carry over). Pass `--rule`, `--file`, or both; neither, or a missing or empty file, is a usage error (exit `2`). If Brava can't reach the compiler the request fails (exit `1`).
28
+
29
+ The output says the run checked undeployed rule text, and the console is never refreshed for it (`consoleUpdate` is `null`). When `brava run test` could not inject telemetry for the rule, an informational line says why (`injectionBlocker` in `--json`: `NOT_TELEMETRY_DRIVEN` the rule reads no event data, `QUERY_UNPARSEABLE` the text could not be parsed for planning, `REFLIST_MEMBER_UNKNOWN` the rule is gated on a reference list with no readable entries); it never changes the exit code. Stale reference lists the rule reads are listed with the source warnings. Feed and log-volume warnings aren't shown for `--file`: they describe the SIEM, not the rule.
30
+
31
+ Data checks (log types receiving events, populated fields, parsers) run on the `--siem` SIEM. For a Dev SIEM that doesn't receive every source, set its **Fallback Telemetry Source** integration setting to the production SIEM: log types with no data in Dev are then measured there, read-only, and the Q1 detail names them. Without it, a rule reading a log type Dev doesn't receive fails Q1.
32
+
33
+ Pull-request pipeline (needs `jq`; `create --json` prints the run, including its `id`):
34
+
35
+ ```bash
36
+ id=$(brava run sweep create --siem "Google SecOps" --file rules/x.yaral --json | jq -r .id)
37
+ brava run sweep watch "$id" --fail-on high
38
+ ```
39
+
40
+ Documentation: https://docs.brava.security/cli/
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "brava-cli"
3
- version = "0.3.0"
3
+ version = "0.4.0"
4
4
  description = "Brava Security CLI"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -261,14 +261,24 @@ class BravaClient:
261
261
  def get_detection_test(self, test_id: str) -> dict[str, object]:
262
262
  return _object(self._get(f"/api/v1/hygiene/detection-test/{test_id}"))
263
263
 
264
- def start_rule_sweep(self, integration_id: str, rule: str) -> dict[str, object]:
265
- """Raises ``httpx.HTTPStatusError`` on 409 so callers can retry."""
264
+ def start_rule_sweep(
265
+ self, integration_id: str, rule: str | None, rule_text: str | None = None
266
+ ) -> dict[str, object]:
267
+ """Raises ``httpx.HTTPStatusError`` on 409 so callers can retry.
268
+
269
+ With ``rule_text``, ``rule`` names the live rule the text would replace (optional).
270
+ """
271
+ body: dict[str, str] = {"integrationId": integration_id}
272
+ if rule is not None:
273
+ body["ruleId"] = rule
274
+ if rule_text is not None:
275
+ body["ruleText"] = rule_text
266
276
  return _object(
267
277
  self._request(
268
278
  "POST",
269
279
  "/api/v1/hygiene/rule-sweep",
270
280
  passthrough=(httpx.codes.CONFLICT,),
271
- json={"integrationId": integration_id, "ruleId": rule},
281
+ json=body,
272
282
  )
273
283
  )
274
284
 
@@ -5,6 +5,7 @@ import functools
5
5
  import time
6
6
  from collections.abc import Callable
7
7
  from dataclasses import dataclass
8
+ from pathlib import Path
8
9
  from typing import Annotated
9
10
 
10
11
  import httpx
@@ -21,7 +22,7 @@ from brava_cli.siems import resolve_siem_id
21
22
  from brava_cli.types import as_dicts, as_str
22
23
 
23
24
  Run = dict[str, object]
24
- Start = Callable[[BravaClient, str, str], Run]
25
+ Start = Callable[[BravaClient, str], Run]
25
26
  Fetch = Callable[[BravaClient, str], Run]
26
27
 
27
28
  SiemOption = Annotated[
@@ -71,6 +72,13 @@ _CONSOLE_UPDATE = {
71
72
  style="red",
72
73
  ),
73
74
  }
75
+ _INJECTION_BLOCKER = {
76
+ "NOT_TELEMETRY_DRIVEN": "the rule reads no event data, so `brava run test` "
77
+ "cannot inject telemetry for it",
78
+ "QUERY_UNPARSEABLE": "the rule text could not be parsed to plan an injection test",
79
+ "REFLIST_MEMBER_UNKNOWN": "the rule is gated on a reference list with no "
80
+ "readable entries, so `brava run test` cannot build matching events",
81
+ }
74
82
 
75
83
 
76
84
  @dataclass(frozen=True, kw_only=True)
@@ -155,9 +163,29 @@ def render(run: Run) -> Group:
155
163
  parts.append(sources)
156
164
  else:
157
165
  parts.append(Text("No log type or feed warnings"))
158
- console_update = _CONSOLE_UPDATE.get(as_str(run.get("consoleUpdate")))
159
- if console_update is not None:
160
- parts.append(console_update)
166
+ if run.get("fromRuleText") is True:
167
+ replaces = as_str(run.get("ruleId"))
168
+ parts.append(
169
+ Text(
170
+ "Checked undeployed rule text (nothing was changed in the SIEM)"
171
+ + (f"; it would replace live rule {replaces}" if replaces else "")
172
+ + "; the console is not updated for undeployed rules",
173
+ style="cyan",
174
+ )
175
+ )
176
+ else:
177
+ console_update = _CONSOLE_UPDATE.get(as_str(run.get("consoleUpdate")))
178
+ if console_update is not None:
179
+ parts.append(console_update)
180
+ blocker = as_str(run.get("injectionBlocker"))
181
+ if blocker:
182
+ why = _INJECTION_BLOCKER.get(blocker, blocker)
183
+ parts.append(
184
+ Text(
185
+ f"Injection test not possible: {why} (does not affect the result)",
186
+ style="dim",
187
+ )
188
+ )
161
189
  reason = as_str(run.get("inconclusiveReason"))
162
190
  name = as_str(run.get("ruleName")) or as_str(run.get("ruleId"))
163
191
  error = as_str(run.get("error"))
@@ -179,16 +207,14 @@ def _show(ctx: CliContext, run: Run) -> None:
179
207
  ctx.console.print(render(run))
180
208
 
181
209
 
182
- def _create(
183
- kind: _Kind, start: Start, siem: str, rule: str, timeout: str, json: bool
184
- ) -> None:
210
+ def _create(kind: _Kind, start: Start, siem: str, timeout: str, json: bool) -> None:
185
211
  deadline = time.monotonic() + _seconds(timeout)
186
212
  ctx = resolve_context(json)
187
213
  integration_id = resolve_siem_id(ctx.client, siem)
188
214
  noun = kind.noun
189
215
  while True:
190
216
  try:
191
- run = start(ctx.client, integration_id, rule)
217
+ run = start(ctx.client, integration_id)
192
218
  break
193
219
  except httpx.HTTPStatusError as exc:
194
220
  if exc.response.status_code != httpx.codes.CONFLICT.value:
@@ -303,14 +329,51 @@ def _run_app(kind: _Kind, create: Callable[..., None], help: str) -> typer.Typer
303
329
  return sub
304
330
 
305
331
 
332
+ def _read_rule_text(path: Path) -> str:
333
+ try:
334
+ text = path.read_text(encoding="utf-8")
335
+ except (OSError, UnicodeDecodeError) as exc:
336
+ raise typer.BadParameter(f"cannot read {path}: {exc}", param_hint="--file")
337
+ if not text.strip():
338
+ raise typer.BadParameter(f"{path} is empty", param_hint="--file")
339
+ return text
340
+
341
+
306
342
  def sweep_create(
307
343
  siem: SiemOption,
308
- rule: RuleOption,
344
+ rule: Annotated[
345
+ str | None,
346
+ typer.Option(
347
+ "--rule",
348
+ help="Live rule id or exact display name; with --file, the live rule "
349
+ "the file's text would replace",
350
+ ),
351
+ ] = None,
352
+ file: Annotated[
353
+ Path | None,
354
+ typer.Option(
355
+ "--file",
356
+ help="YARA-L rule text file to check before it is deployed; nothing is "
357
+ "uploaded or changed in the SIEM",
358
+ ),
359
+ ] = None,
309
360
  timeout: SlotTimeoutOption = DEFAULT_SLOT_TIMEOUT,
310
361
  json: JsonOption = False,
311
362
  ) -> None:
312
- """Start a rule sweep; prints its id. Exit 3 if the SIEM stays busy past --timeout."""
313
- _create(_SWEEP, BravaClient.start_rule_sweep, siem, rule, timeout, json)
363
+ """Start a rule sweep; prints its id. Exit 3 if the SIEM stays busy past --timeout.
364
+
365
+ Needs --rule (live rule), --file (undeployed rule text, a new rule) or both
366
+ (undeployed text that would replace the live --rule).
367
+ """
368
+ if rule is None and file is None:
369
+ raise typer.BadParameter(
370
+ "pass --rule, --file, or both", param_hint="'--rule' / '--file'"
371
+ )
372
+ rule_text = _read_rule_text(file) if file is not None else None
373
+ start = functools.partial(
374
+ BravaClient.start_rule_sweep, rule=rule, rule_text=rule_text
375
+ )
376
+ _create(_SWEEP, start, siem, timeout, json)
314
377
 
315
378
 
316
379
  def detection_test_create(
@@ -324,15 +387,18 @@ def detection_test_create(
324
387
  json: JsonOption = False,
325
388
  ) -> None:
326
389
  """Start a detection test; prints its id. Exit 3 if the SIEM stays busy past --timeout."""
327
- start = functools.partial(BravaClient.start_detection_test, inject=not dry_run)
328
- _create(_TEST, start, siem, rule, timeout, json)
390
+ start = functools.partial(
391
+ BravaClient.start_detection_test, rule=rule, inject=not dry_run
392
+ )
393
+ _create(_TEST, start, siem, timeout, json)
329
394
 
330
395
 
331
396
  sweep_app = _run_app(
332
397
  _SWEEP,
333
398
  sweep_create,
334
- "Single-rule hygiene sweep: the checks a full sweep runs, on the live rule, "
335
- "then a refresh of that rule in the console (Google SecOps)",
399
+ "Single-rule hygiene sweep: the checks a full sweep runs, on a live rule "
400
+ "(then a refresh of that rule in the console) or on undeployed rule text "
401
+ "from --file (Google SecOps)",
336
402
  )
337
403
  detection_test_app = _run_app(
338
404
  _TEST,
brava_cli-0.3.0/PKG-INFO DELETED
@@ -1,36 +0,0 @@
1
- Metadata-Version: 2.5
2
- Name: brava-cli
3
- Version: 0.3.0
4
- Summary: Brava Security CLI
5
- Requires-Python: >=3.10
6
- Requires-Dist: httpx>=0.28.0
7
- Requires-Dist: python-dotenv>=1.0.0
8
- Requires-Dist: rich>=13.0.0
9
- Requires-Dist: typer>=0.15.0
10
- Description-Content-Type: text/markdown
11
-
12
- # Brava CLI
13
-
14
- Command-line access to the [Brava Security](https://brava.security) platform for attack simulation and SIEM hygiene, built for terminals and CI.
15
-
16
- ```bash
17
- pip install brava-cli # or: uv tool install brava-cli
18
- export BRAVA_URL=https://console.brava.security
19
- export BRAVA_API_TOKEN=brava_… # API key from Settings → API Keys
20
- brava doctor # shows which products your key can read
21
- ```
22
-
23
- Or store credentials once with `brava auth login --token <key>` (`--url` defaults to `https://console.brava.security`); `BRAVA_URL` / `BRAVA_API_TOKEN` override stored values.
24
-
25
- | Product | API key scopes | Commands |
26
- |---|---|---|
27
- | Attack simulation | `simulations:run` | `brava catalog`, `brava run simulation`, `brava run goal` |
28
- | Hygiene | `hygiene:read`, `hygiene:detections:test` | `brava siems list`, `brava run sweep`, `brava run test` |
29
-
30
- With an API key, `brava run simulation|goal …` work when `--account-id` is the Brava environment UUID; `brava accounts list` and lookup by name or cloud account id are not available to API keys yet.
31
-
32
- `brava doctor` marks a product NO ACCESS when the key lacks that product's read scope (`simulations:run`, `hygiene:read`); it exits `0` only when no check fails and at least one product is accessible (HTTP 200).
33
-
34
- `brava run sweep watch` and `brava run test watch` exit `0` pass, `1` request, auth or validation error (e.g. a bad `--timeout`, missing URL/token), `2` gate failed (a hygiene check failed or a finding at/above `--fail-on`, default `high`) or a usage error caught while parsing arguments (e.g. `--fail-on bogus`, a missing run id), `3` timed out (run continues), `4` no answer (run FAILED/CANCELLED, verdict UNKNOWN, or an injection test (not a dry run) INCONCLUSIVE/NOT_TELEMETRY_DRIVEN). A sweep's log-type and feed warnings never change the exit code. `brava run test create --dry-run` runs the hygiene checks only and is judged like a sweep.
35
-
36
- Documentation: https://docs.brava.security/cli/
brava_cli-0.3.0/README.md DELETED
@@ -1,25 +0,0 @@
1
- # Brava CLI
2
-
3
- Command-line access to the [Brava Security](https://brava.security) platform for attack simulation and SIEM hygiene, built for terminals and CI.
4
-
5
- ```bash
6
- pip install brava-cli # or: uv tool install brava-cli
7
- export BRAVA_URL=https://console.brava.security
8
- export BRAVA_API_TOKEN=brava_… # API key from Settings → API Keys
9
- brava doctor # shows which products your key can read
10
- ```
11
-
12
- Or store credentials once with `brava auth login --token <key>` (`--url` defaults to `https://console.brava.security`); `BRAVA_URL` / `BRAVA_API_TOKEN` override stored values.
13
-
14
- | Product | API key scopes | Commands |
15
- |---|---|---|
16
- | Attack simulation | `simulations:run` | `brava catalog`, `brava run simulation`, `brava run goal` |
17
- | Hygiene | `hygiene:read`, `hygiene:detections:test` | `brava siems list`, `brava run sweep`, `brava run test` |
18
-
19
- With an API key, `brava run simulation|goal …` work when `--account-id` is the Brava environment UUID; `brava accounts list` and lookup by name or cloud account id are not available to API keys yet.
20
-
21
- `brava doctor` marks a product NO ACCESS when the key lacks that product's read scope (`simulations:run`, `hygiene:read`); it exits `0` only when no check fails and at least one product is accessible (HTTP 200).
22
-
23
- `brava run sweep watch` and `brava run test watch` exit `0` pass, `1` request, auth or validation error (e.g. a bad `--timeout`, missing URL/token), `2` gate failed (a hygiene check failed or a finding at/above `--fail-on`, default `high`) or a usage error caught while parsing arguments (e.g. `--fail-on bogus`, a missing run id), `3` timed out (run continues), `4` no answer (run FAILED/CANCELLED, verdict UNKNOWN, or an injection test (not a dry run) INCONCLUSIVE/NOT_TELEMETRY_DRIVEN). A sweep's log-type and feed warnings never change the exit code. `brava run test create --dry-run` runs the hygiene checks only and is judged like a sweep.
24
-
25
- Documentation: https://docs.brava.security/cli/
File without changes