soc-bridge-readonly
by HianSoares
README.md
# KiroBridgerMCP

**Investigate a QRadar offense or a Trend Vision One Workbench alert from Kiro using just its ID.**
Kiro connects to one local MCP server, `soc-bridge-readonly`. The bridge gathers bounded evidence from the [IBM QRadar MCP](https://github.com/IBM/qradar-mcp) and [Trend Vision One MCP](https://github.com/trendmicro/vision-one-mcp-server), then returns a report with findings, possible links, and collection gaps. Matching an IP or time is a lead, not proof of a shared incident.
```text
Kiro → SOC Bridge → QRadar MCP + Trend Vision One MCP → evidence report
```
## Try the demo on Windows
You need Git, Python 3.11+, and Kiro IDE. The synthetic demo needs no Docker or product credentials. Run these commands in **PowerShell**:
```powershell
git clone https://github.com/HianSoares/KiroBridgerMCP.git
Set-Location .\KiroBridgerMCP
Test-Path .\pyproject.toml # Expected: True
py -3 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -e .
& .\.venv\Scripts\python.exe -m soc_bridge.cli demo --output reports\demo
& .\.venv\Scripts\python.exe .\scripts\configure_kiro.py
```
Open this **same folder** in Kiro. Under **MCP Servers**, confirm that `soc-bridge-readonly` is connected. Then ask:
> Call `investigate_demo` and explain the evidence and collection limits.
The configurator creates `.kiro/settings/mcp.json` locally; it is not included in the clone. The demo writes `reports/demo.md` and `reports/demo.json` with fabricated data.
For macOS/Linux commands, Docker setup, QRadar and Trend credentials, and a live connection check, follow the [full installation guide (Portuguese)](docs/guia-instalacao.md).
**Kiro on Windows with the bridge in WSL 2?** Follow the [WSL guide (Portuguese)](docs/guia-wsl.md). Kiro for Windows starts MCP servers as Windows processes, so it cannot run the `.venv/bin/python` path that `configure_kiro.py` writes inside WSL. `scripts/configure_kiro_wsl.py` configures `soc-bridge-readonly` to start through `wsl.exe` instead, and `scripts/wsl_preflight.py` checks the setup end to end without credentials.
## Update an existing installation
Close Kiro, then run this from the project folder in PowerShell (no venv activation needed):
```powershell
.\bridger --update
```
The updater fetches `origin/master`, fast-forwards the local `master`, installs into this project's `.venv`, and runs the synthetic tests plus registry/coverage checks. It stops on tracked edits, unmerged local commits, file collisions or a failed step. It preserves personal files and the ignored MCP configuration; it never resets, stashes, pushes or starts services. This updates this repository, not Docker or the upstream MCP installations. See [update requirements and recovery (Portuguese)](docs/guia-instalacao.md#10-atualize-com-um-comando).
## Investigate a real case
Clear investigation requests authorize the required read-only pivots. Completed reports survive connection shutdown errors; partial evidence and known Ariel search IDs are preserved. See [execution and resumption (Portuguese)](docs/investigation-recovery.md) for the temporary alert cache and recovery limits.
After completing the live setup in the guide, give Kiro a QRadar offense number or a Vision One Workbench alert ID:
> Investigate offense `<OFFENSE_ID>` end to end. Show the evidence, decision, confidence, pending checks and a draft note.
> Use `investigate_case` with reference `WB-EXAMPLE-20260924-00001`. Explain which endpoint details were retrieved and which remain unverified.
The bridge exposes seven investigation tools to Kiro: `investigate_case`, `investigate_offense`, `investigate_vision_alert`, `investigate_vision_event`, `investigate_epm_uac`, `investigate_web_reputation`, and `investigate_demo`. Project steering, skills, and agents under `.kiro/` provide focused investigation workflows. Kiro only needs the `soc-bridge-readonly` MCP entry; the bridge connects to the upstream servers.
## Run custom AQL from Kiro
Six additional `qradar_*` tools let Kiro read live field/function metadata, validate and execute custom AQL, inspect events/flows and selected `UTF8(payload)`, and resume/paginate an existing search ID. These tools use QRadar alone and do not require Trend credentials. Read-only mode permits Ariel search jobs.
> Read AQL metadata, then use `qradar_run_aql` to collect the missing evidence for this case. Keep the search ID, use the verified time window, and report pagination and truncation.
See [custom AQL setup, examples and limits](docs/dynamic-aql.md). Offense investigations now also collect INOFFENSE events/flows, a COUNT/UNIQUECOUNT census, contributing rule metadata and a separate host context. The legacy IP samples remain labelled as context.
## Verify an offense before concluding
`qradar_verify_offense` performs the QRadar collection without Trend credentials; `qradar_get_rule` reads contributing rule metadata. Together with the existing tools, the bridge exposes **33 tools** (30 read-only; the two case tools write only the local case store and `upstream_download` saves binary bodies locally). The report distinguishes original metadata times, observed event times and padded collection windows, follows result pages within a budget and preserves unresolved count/payload/attribution gaps.
> Use `qradar_verify_offense` with the offense ID. Resume pending search IDs and collect missing evidence before assessing the case. For a historical case, confirm the actual QRadar timezone before setting `timezone_verified=true`.
The verification reads live field metadata and uses optional Windows/Sysmon properties only when they are listed. It polls pending jobs by the same search ID within an explicit time/job/page budget and returns a `continuation_plan` (search ID, cursor, AQL, scope, reason) instead of recreating searches. When linked records show processes, it reports process creations with GUID+host parent links, PowerShell 4104/4103 content and 5038 code-integrity records as separate evidence classes, with structured gaps per conclusion. Collected telemetry is parsed as data and never executed.
A DHCP-compatible port pattern supports a preliminary hypothesis. It does not establish authorization, successful authentication, endpoint health or a false positive. See [verification workflow and decision limits](docs/offense-verification.md).
Linux records now receive a census of sudo actors, targets and commands across all collected pages, plus separate SSH and su/PAM searches bounded to the original offense interval. The report reads the optional live closing-reason catalog and supplies a reviewable decision, rationale and Portuguese note draft. Kiro can recommend a specific reason after cited evidence resolves the relevant gaps; it never closes the offense or posts the note.
## Investigate a Vision One alert
`investigate_vision_alert` parses Workbench `impactScope` entities, typed indicators and matched rules with provenance, then searches endpoint/detection data and OAT by the alert's own identifiers (not the model name) under a shared time/call/record/partition budget. Search has no continuation token in the official MCP, so full pages are split into time partitions; OAT pages by `nextBatchToken`. Optional read-only enrichments (notes, inventory, DMM, intel lists, cases, existing sandbox results and response tasks) report missing tools, permissions and licenses separately. QRadar correlation reuses the budgeted Ariel collector with epoch predicates, and each Trend↔QRadar relation is labelled confirmed, candidate or unverified. The report ends with a recommended classification and a Portuguese note for human review; nothing is closed, posted or executed. Set `QRADAR_AQL_TIMEZONE_VERIFIED=true` only after confirming the console offset for historical windows. See [Trend alert investigation](docs/trend-alert-investigation.md).
## Investigate an offense end to end (persistent case)
Ask Kiro: "Investigue a offense 12345". `investigate_offense_case` collects offense-linked records, resumes known Ariel jobs from their saved cursors instead of recreating them, deepens related Trend alerts when Vision One is available, separates observed behavior from rule names, builds competing hypotheses, plans the next pivots (hypothesis, motivation, cost, stop criterion) and evaluates each disposition and live closing reason with explicit contradictions. Analyst records count only within their scope: each observed instance is checked by entity, process/chain and a window with an explicit timezone. Authorizations name a behavior (exact command, script, artifact, instance, sudo command or an explicitly declared breadth), never just an executable or account. A related Trend True Positive confirms malicious activity only when the offense-linked process is the malicious Trend execution or its demonstrated parent/child; a shared hash, IP or time stays a candidate. Trend facts are kept per alert: an inconclusive or failed re-collection never erases them, and only cited evidence refutes them. The result is a decision with justified confidence (no numeric score), decisive evidence with query/row references and a Portuguese note for human review. The case is stored locally in `reports/cases` (ignored by Git) under an inter-process lock, with checkpoints during collection; it belongs to one offense, can be continued with the same `case_id` after an interruption and re-evaluated with `reassess_case` from the stored QRadar and Trend results without new queries; earlier report revisions are kept. `soc-bridge doctor` / `bridge_diagnostics` show versions, connection stages and paginated tool discovery without secrets. See [professional investigation](docs/professional-investigation.md) and [case store](docs/case-store.md).
## Route any audited upstream tool
All 432 tools of the audited official MCPs have a route; a route does not prove a tool works.
- **Read tools (255):** 53 QRadar and 202 Vision One tools are callable through five `upstream_*` tools on `soc-bridge-readonly`. Kiro searches an audited registry by objective, reads the exact contract, then calls a tool with schema-validated arguments. No offense or Workbench ID is needed.
- **Change tools (177):** these change state, send data out or upload files (the ten Vision One uploads use an approved, hash-checked staged copy). They run only from a separate `soc-bridge-change` server, which is disabled by default and needs a human approval typed in a terminal for each call.
- **Evidence:** all tools pass schema and route checks. Only 15 were tested end to end, against synthetic servers. None has been executed against a real tenant yet.
See [upstream access](docs/upstream-access.md) and the [coverage matrix](docs/coverage-matrix.md).
## Investigative coverage and closure decisions
The curated investigation workflows call 34 QRadar MCP tools (GET reads plus Ariel validation/search creation) and 40 Trend Vision One MCP tools automatically, each with a trigger, limits and handler-verified pagination. Alert investigations run in budgeted phases (primary evidence, hypothesis checks, reserved Trend↔QRadar correlation, optional enrichments), keep Insight values with explicit truncation, and offense investigations deepen up to two related Workbench alerts without recursion. `qradar_read_context` reads rules, building blocks, QIDs, log sources, assets and reference data by validated arguments; `qradar_assess_closure` evaluates each live closing reason against its own requirements and accepts cited analyst records. Conclusions use explicit evidence statuses instead of scores; nothing is closed or posted. See [investigative coverage (Portuguese)](docs/investigative-coverage.md).
## Scope and safety
- Investigations use limited searches. No Workbench alert or no result on an inspected page does **not** mean there was no endpoint activity.
- An alert may omit its View event fields. Automatically discovered hosts, hashes, and IPs are labelled as candidates; analyst-supplied fields are not independently verified by the bridge.
- `soc-bridge-readonly` does not block domains, isolate endpoints, close offenses, or change product settings. Those operations exist only in the disabled `soc-bridge-change` server. Verify account permissions for your deployment.
- Live reports may contain sensitive telemetry and enter the context of the AI model configured in Kiro. Keep credentials and `reports/` out of public repositories and follow your organization's data policy.
See [known limitations](docs/bridge-known-limitations.md), the [Kiro pack notes](README-kiro-pack.md), and the [engineering backlog](BRIDGE-BACKLOG.md) for details. Licensed under [MIT](LICENSE).
Offenses sharing a description can be discovered with `qradar_find_offenses` and investigated in bounded batches with `qradar_investigate_offenses`. Each case keeps its own evidence, continuation and closing-note draft. See [batch investigations](docs/offense-batch-investigation.md).
To list all OPEN offenses without a description, use `qradar_list_offenses`. It orders returned metadata by magnitude, severity, credibility, relevance and recency, with explicit criteria and no calculated risk score. Follow its continuation cursors and re-sort the combined population before claiming a global investigation order. Listing does not start case investigations. See [queue triage](docs/offense-batch-investigation.md#list-the-open-queue-and-prioritize-investigation).
### Discover Trend alerts without an ID
Ask Kiro: "Veja se há alertas abertos na Trend nas últimas 24 horas." It calls `trend_find_alerts(status="OPEN")`, including Open and In Progress, with no QRadar connection. Filter by severity or provide both ISO time bounds (maximum 30 days). Results include WB IDs for `investigate_vision_alert`. The official Workbench list MCP handler does not forward a pagination cursor: nextLink, local output caps and collection failures are explicitly distinguished from a complete empty page. This does not enumerate all historical open alerts. See [discovery limits](docs/trend-alert-discovery.md).
### Direct Trend log search
`trend_read_search_resource` reads the live query schema; `trend_search_data` searches endpoint, detections, network, identity, email, cloud, container or mobile data without a WB/offense ID or QRadar connection. Native command/hash/process/object/instance fields are preserved within explicit limits. Full pages split by time; pending windows and dense leaves carry continuation/refinement plans, never invented cursors. Search does not cover every console feature, assert a verdict or mutate data. See [direct Search guide](docs/trend-direct-search.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues