Skip to content

task: document the new sensor taskings, and fix two broken examples - #351

Open
maximelb wants to merge 1 commit into
masterfrom
cli/security-taskings
Open

task: document the new sensor taskings, and fix two broken examples#351
maximelb wants to merge 1 commit into
masterfrom
cli/security-taskings

Conversation

@maximelb

@maximelb maximelb commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Documentation only — no functional change, and none is needed.

The CLI does not parse or validate the task string. task send forwards it to the backend verbatim (commands/task.py:127sdk/sensor.py:118), and the backend generates its own help from the command parser's argument definitions. So dir_find, file_grep, container_list and artifact_get --root-dir already work against the current CLI:

limacharlie task send --sid <SID> --task 'dir_find "C:\Users" -x "*.exe" --with-hashes'

What was missing is discoverability. This adds them to the task send command menu, which also feeds --ai-help through the explain registry.

I also noted the budget convention once: a bounded search stops at the first budget reached and reports it in SCAN_IS_TRUNCATED / SCAN_STOPPED_REASON, so an empty result is not necessarily a clean host.

Rather than inline ~15 flags per command — this menu has never carried flags for any command — the text points at the backend reference, which is the authority on them.

Two pre-existing bugs, same lines

Both verified against the actual Click options rather than assumed:

  • The incident-response cheatsheet (help_topics.py) told users to pass --args to task send, which accepts only --sid, --task and --investigation-id. Both examples errored out on copy-paste. Rewritten as task strings, matching the form the reference documentation uses.
  • doc/cli/sensor-management.md used task send --command. send takes --task; --command belongs to request and reliable-send.

Context

repo_list and usb_list_devices are also absent from this menu — this list has drifted from the backend for a while. I did not add them here to keep the change scoped, but they are worth a follow-up.

Validation

  • pytest — 4005 passed, 5 skipped
  • Confirmed the rendered --ai-help text and cheatsheet output, not just the source

The CLI does not parse or validate the task string -- it forwards it to
the backend verbatim -- so dir_find, file_grep, container_list and
artifact_get --root-dir already work today. This is documentation only.

Add them to the 'task send' command menu, which also feeds --ai-help via
the explain registry, and note the budget convention: a bounded search
stops at the first budget reached and says so in SCAN_IS_TRUNCATED and
SCAN_STOPPED_REASON, so an empty result is not necessarily a clean host.

Point the reader at the backend reference for the full flag set rather
than inlining ~15 flags per command, since this menu has never carried
flags and the backend is the authority on them.

Two pre-existing bugs in the same lines, both verified against the actual
Click options:

- The incident-response cheatsheet told users to pass --args to
  'task send', which accepts only --sid, --task and --investigation-id.
  Both examples errored out. Rewritten as task strings, matching the form
  the reference documentation uses.
- doc/cli/sensor-management.md used 'task send --command'. 'send' takes
  --task; --command belongs to 'request' and 'reliable-send'.

Verified: 4005 passed, 5 skipped.
@maximelb

maximelb commented Sep 2, 2026

Copy link
Copy Markdown
Contributor Author

/lc-review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants