diff --git a/README.md b/README.md index 63a3b92..ea3ccd1 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,33 @@ Or use the helper script, which creates/uses `.venv` automatically and runs `pip - Continuous monitor writing `state/fgai-status.json` - Local dashboard at `http://127.0.0.1:8088` +## Dashboard How To + +The dashboard is the normal way to run SignalScope once the service is started. +It is organized around the operational workflow: + +1. Open `Settings`. +2. Select `Graylog MCP`. +3. Enter the Graylog MCP URL and token, then save. +4. Click `Load streams`. +5. Enable the streams you want SignalScope to monitor, then save again. +6. Apply missing recommended profiles, or click `Edit profile` on a stream to + choose its entity, time, baseline, detector, and weight fields manually. +7. Let the baseline learn for the configured `Baseline training days` before + treating every deviation as actionable. +8. Use `Overview` for incidents, trends, stream health, AI assessment, and the + correlation map. +9. Use `Findings` for the triage queue, field baseline deviations, related + activity across sources, threat intelligence, and policy findings. +10. Use `Diagnostics` to confirm stream coverage, MCP fetch health, profile + readiness, data quality, and normalized top fields. +11. Mark findings as `Expected`, `False positive`, or `Confirmed` so repeated + known behavior is labeled and lower priority in later refreshes. + +The UI also includes a `How To` tab with the same operational checklist. Use it +when adding new streams or when the dashboard has data but it is unclear what +needs attention next. + ## Primary Workflow: Graylog MCP Graylog 7.1 MCP is the primary log-source integration. In the dashboard, open @@ -99,6 +126,16 @@ see which streams are enabled, which have profiles, how many profile fields are baseline-ready, how many events were fetched, and whether a stream is `ready`, `learning`, `missing_profile`, `no_events`, or `not_enabled`. +Recommended stream profiles are an onboarding helper, not a fixed FortiGate +parser. SignalScope inspects the fields observed from each Graylog stream and +looks for common denominator fields such as entities, timestamps, actions, +severities, categories, ports, DNS names, URLs, process fields, Windows event +IDs, and numeric counters. Fields that appear across multiple enabled streams +are preferred when they are useful for correlation or baselining. The local +Ollama profile advisor can refine those recommendations, but the deterministic +profile discovery remains the fallback when Ollama is disabled, missing, slow, or +returns invalid JSON. + Enabled streams are normalized through the same event model. Stream profiles define the entity, timestamp, categorical, and numeric fields used for baselines. The dashboard and Ollama then correlate behavior across sources, for example a @@ -141,6 +178,13 @@ Use the dashboard incident actions to acknowledge, resolve, or reopen an inciden and attach a note. The state is keyed to a stable incident fingerprint so it can survive monitor refreshes even when the current detection window changes. +Field deviation review state is stored locally as feedback. Mark a deviation as +`Expected`, `False positive`, or `Confirmed` from the Findings page. The decision +is scoped to the stream, entity, field or detector pattern, optional value, note, +and expiry time. Expected and false-positive feedback does not erase the finding; +it keeps the row reviewable while reducing repeat noise for the same scoped +pattern and giving Ollama context that the behavior is already known. + Export the current investigation view when you need to share or archive an incident outside the dashboard: diff --git a/src/fgai/dashboard.py b/src/fgai/dashboard.py index d08c0a4..7e7bd90 100644 --- a/src/fgai/dashboard.py +++ b/src/fgai/dashboard.py @@ -106,6 +106,11 @@ HTML = """ .sort-button:hover { color: #d9e8f7; } .model-list { display: flex; flex-wrap: wrap; gap: 8px; } .model-pill { border: 1px solid #39709a; background: #08243e; color: #d9e8f7; padding: 5px 8px; cursor: pointer; } + .howto-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 12px; } + .howto-card { border: 1px solid #163b59; background: #061a2e; border-radius: 6px; padding: 12px; } + .howto-card h3 { margin: 0 0 8px; font-size: 16px; color: #83bce9; } + .howto-card ol, .howto-card ul { margin: 0; padding-left: 20px; } + .howto-card li { margin: 6px 0; } @media (max-width: 860px) { .hero, .split { grid-template-columns: 1fr; } .hero img { display: none; } } @@ -119,11 +124,12 @@ HTML = """

Live Status

Waiting for monitor data.
- +

Events and Anomalies

Baseline and Stream Health

Correlation Map

AI Assessment

LLM assessment disabled.

Investigation Incidents

Anomalies

Recommendations

Triage Queue

Field Baseline Deviations

Related Activity Across Sources

Block Candidates

Threat Intelligence

Policy Findings

Diagnostics

Recommended Stream Profiles

Waiting for observed stream data.

Installed Ollama Models

Loading local Ollama models.

Runtime Configuration

+

How To Use SignalScope

1. Connect Logs

  1. Open Settings and select Graylog MCP.
  2. Save the MCP URL and token.
  3. Click Load streams, enable the streams you want monitored, then save.

2. Create Profiles

  1. Use Recommended Stream Profiles first.
  2. Click Apply profile for missing streams.
  3. Use Edit profile when a stream needs custom entity, time, baseline, detector, or weight fields.

3. Let Baselines Learn

  1. Set Baseline training days to the history window you trust.
  2. Use Diagnostics to see profile readiness per stream and field.
  3. Treat early findings as learning signals until fields are ready.

4. Investigate Findings

  1. Start with Overview incidents and the correlation map.
  2. Use Findings for triage, field deviations, related activity, and reputation.
  3. Open evidence rows to see samples and Graylog query details.

5. Review Noise

  1. Mark deviations as Expected, False positive, or Confirmed.
  2. Use expiry days when expected behavior should be temporary.
  3. Reviewed expected patterns stay labeled and reduce repeat noise for the same scope.

6. Production Settings

  • Use aggregate or auto fetch mode for high EPS streams.
  • Keep the poll window around 300 seconds unless you know Graylog can handle more.
  • Enable Ollama only when local models are installed.
  • Add threat intel API keys only if you want external public-IP reputation checks.