Generic tag-probing + Sophos Central events/alerts polling

[yokoszn]

Closes #18.

Research recap

A crawl of the official Sophos tooling (details in #18) surfaced two steal-worthy patterns and one correction worth calling out here:

• sophos/sophos-firewall-sdk: generic get_tag(xml_tag=...) fetches any XML entity, documented or not — the validation path for hypothesized entity names instead of waiting on docs. A live Sophos docs page path (.../API/PROTECT/Wireless/wirelessgrouping/...) confirms Wireless is a real, documented API section.
• sophos/Sophos-Central-SIEM-Integration: OAuth2 client-credentials auth (id.sophos.com/api/v2/oauth2/token), tenant/region resolution via whoami/v1, and /siem/v1/events + /siem/v1/alerts polling with a JSON cursor file for resume.
• Correction from the initial research pass: those Central endpoints have no server-side product/category filter — confirmed by reading api_client.py/config.ini.sample/name_mapping.py directly (no wireless entries anywhere). "Wireless-only" filtering has to happen client-side on the type field, and the exact type string is unconfirmed without a live tenant with an enrolled AP.

What this PR adds

sfos-sdk

• central module (new): a Sophos Central cloud API client — OAuth2 auth with token caching, whoami tenant/region resolution, /siem/v1/events and /siem/v1/alerts polling (PollQuery/EventsPage), and CentralState for JSON-file cursor persistence across runs. is_wireless_event() is the best-effort, explicitly-caveated client-side type filter.
• registry: new Wireless category — WirelessGrouping (corroborated by the docs path above) plus three unconfirmed sibling-tag guesses (WirelessNetwork, AccessPoint, MeshNetwork), documented as such. export/export_all now probe these resiliently like every other entity.

sfos-cli

• probe <TAG>...: fire ad-hoc Get requests at a live firewall for arbitrary tag names and report per-tag OK/element-count/error — for validating a hypothesized entity name (e.g. probe AccessPoint WirelessAP WirelessAccessPointStatus) before it earns a spot in the registry.
• central-events / central-alerts: poll one page from Sophos Central and persist the resume cursor to --state-file (default state/central-cursor.json); --wireless-only applies the best-effort filter above. Auth via --client-id/--client-secret/--tenant-id or SFOS_CENTRAL_CLIENT_ID/SFOS_CENTRAL_CLIENT_SECRET/SFOS_CENTRAL_TENANT_ID.

Docs: README.md, docs/cli-reference.md, docs/sdk-guide.md, docs/playbooks.md, CHANGELOG.md updated for the new commands/module and the registry's new entity/category counts (66→70 entities, 15→16 categories).

Not in this PR: the third build-order step (netmiko-style Device Console scripting for wireless-controller debug/pktcap) — deferred until steps 1–2 show what structured signal actually exists on a live box/tenant.

Test plan

• cargo build --workspace — clean
• cargo test --workspace — 47/47 passing (all offline; the Central/XML HTTP round-trips can't be exercised without live credentials, same convention as the existing client module — request-building, token-caching/expiry, and cursor-state logic are unit-tested)
• cargo clippy --workspace --all-targets — clean
• cargo fmt --check — clean
• Manually exercised --help for probe and central-events, and entities to confirm the new Wireless category renders
• probe/central-events/central-alerts against a live firewall/tenant (needs real credentials — flagged as the next step in Wireless AP monitoring: research findings + build order #18)

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@yokoszn, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 54 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e22f705f-b47c-42ad-a035-b925599b1f8a

📥 Commits

Reviewing files that changed from the base of the PR and between 7f5333f and a959808.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (10)

• CHANGELOG.md
• README.md
• crates/sfos-cli/src/main.rs
• crates/sfos-sdk/Cargo.toml
• crates/sfos-sdk/src/central.rs
• crates/sfos-sdk/src/lib.rs
• crates/sfos-sdk/src/registry.rs
• docs/cli-reference.md
• docs/playbooks.md
• docs/sdk-guide.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/sophos-api-research-f2nuqd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}