Forensics

The Forensics page is a two-pane console. The left pane lists every forensics collection (a report) for your organization; selecting one opens the collected artifacts in the right pane. The header summarises how many collections exist and how many threat indicators were flagged across them.

The collection handshake

A collection is not gathered by the web app directly — it is queued for the endpoint agent to run:

1. You pick a target agent and start a collection. The server creates a ForensicsReport with status pending and queues an EndpointCommand named collect-forensics carrying the new report's id.
2. The agent picks up the command on its next heartbeat (the UI states this happens within about 30 seconds) and gathers the artifacts on the host.
3. The agent posts the collected data back; the report flips to complete, stores the artifacts, and records a collectedAt timestamp.

Report status

Live refresh

The report list re-fetches every 15 seconds. When you have a still-collecting report open, that report is polled every 5 seconds until it finishes, so the view updates itself without a manual reload.

Click Collect Artifacts to open the collection dialog.

Starting a collection

1. Target Agent (required) — choose a host from the dropdown of online agents (each shows hostname, platform and status). If no agents are online, the field becomes a free-text input for a hostname or IP.
2. Reason / Trigger (optional) — a note such as a detection name or incident id. If left blank the collection is recorded as manual.
3. Click Start Collection. The command is queued and a new report appears in the list.

Artifacts the dialog lists

The dialog shows the categories that a collection is expected to return:

• Running processes + command lines
• Active network connections
• Autorun / startup entries
• Scheduled tasks
• Recently modified files (labelled "24h")
• Security event logs (labelled "7 days")

Reviewing a report

• Each report card shows the hostname, who or what triggered it, the status, a process/connection count, a threat count when indicators are present, and a relative timestamp.
• Selecting a completed report opens the artifact viewer, with collapsible sections per artifact category. Sections containing flagged items open automatically.
• Export JSON downloads the raw collected data as a .json file named for the host.
• Delete (on the card or in the detail header) removes the report. The removal is optimistic and rolls back if the server rejects it.

When a report is complete, the viewer renders whichever of these sections the agent returned. Empty sections are hidden.

If the agent returns only a raw text blob instead of structured sections, it is shown verbatim in a fallback panel.

Threat indicators

The viewer applies client-side heuristics to surface likely-malicious artifacts. Matching processes and connections are highlighted in red and summarised in a "Threat Indicators Found" banner at the top of the report.

• Suspicious processes — a process name containing any of: mimikatz, meterpreter, cobalt, empire, lazagne, bloodhound, psexec, netcat, ncat, socat, chisel, ligolo.
• C2 connections — a network connection whose remote port is one of: 4444, 4445, 1234, 5555, 6666, 7777, 8888, 9999, 31337, 1337, 2222, 6667.

The page is backed by two route files. Analyst-facing calls use your logged-in session; the artifact submission path is authenticated by the agent's own token.

Queue a collection

curl -X POST https://app.guardfox.example/api/forensics/collect \
  -H "Content-Type: application/json" \
  -b "next-auth.session-token=" \
  -d '{ "hostname": "WORKSTATION-07", "triggeredBy": "Suspicious process detected" }'

# → { "reportId": "...", "status": "pending",
#     "message": "Collection command queued. Agent will collect on next heartbeat." }

List reports

curl https://app.guardfox.example/api/forensics/reports \
  -b "next-auth.session-token="

# → { "reports": [ { "id": "...", "hostname": "WORKSTATION-07",
#       "triggeredBy": "manual", "status": "complete",
#       "data": { "processes": [...], "network": [...] },
#       "collectedAt": "...", "createdAt": "..." } ] }

The ForensicsReport record stores id, agentId, hostname, triggeredBy (manual / soar / auto), status, the collected artifacts (dataJson), collectedAt, createdAt and the owning organizationId.