diff --git a/README.md b/README.md index a1bb586..e425776 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,71 @@ 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. +## Operating The Dashboard + +Start in `Overview`, not in the long diagnostics tables. The intended daily flow +is: + +1. Read `Operator Guidance` for the next action SignalScope thinks is most useful. +2. Check `Investigation Incidents` for grouped entity-level problems. +3. Use the correlation graph to see whether the same entity appears across + several streams. +4. Open `Findings` only after you have an entity or incident to inspect. +5. Expand evidence rows and use the Graylog query link to inspect the raw events. +6. Mark the finding as `Expected`, `False positive`, or `Confirmed`. + +The top status badges are health indicators: + +- `Graylog MCP: connected` means the last completed MCP query worked. +- `Graylog MCP: refreshing` means a poll is in progress and the UI is showing + previous counters until the poll completes. +- `Graylog MCP: error` means the UI may be showing cached data. Check the MCP + URL, token, DNS/TLS, and stream permissions. +- `Baseline: N sources ready` means historical source-IP baselines exist for + `N` source entities. Profile readiness is checked separately per stream field. +- `Ollama: cached` or `ok` means local LLM output is available. It is supporting + evidence, not the source of truth. + +Use `Diagnostics -> Stream Coverage` to decide whether the monitor is healthy: + +- `ready`: stream is enabled, profile exists, events are arriving, and profile + fields have enough baseline history. +- `learning`: stream is enabled and profiled, but baseline age or bucket count is + still too low. +- `missing_profile`: stream is enabled but no profile exists. Apply a + recommended profile or edit one manually. +- `no_events`: stream is enabled but no raw sample was returned in the last poll. + Check stream activity, query, range, or permissions. +- `partial_fetch`: Graylog returned only part of the raw sample. Use aggregate or + auto mode with a smaller raw sample on high-EPS streams. +- `sample capped`: aggregate mode counted the full window, but raw events were + intentionally capped to keep context queries manageable. + +`Ready Fields` is shown as `ready/tracked`, for example `0/8`. The stream profile +tracks 8 fields, but none of those fields are mature yet. A field needs at least +12 five-minute buckets and the configured `Baseline training days` before it is +ready. With the default seven-day training window, new profiles can show `0/X` +for days even while data is being learned. + +Interpret findings by maturity: + +- During `learning`, findings are mostly profile-tuning signals. +- When fields are `ready`, high-score deviations are more meaningful. +- `new_relationship` means a new field pair appeared, such as + `username -> srcip` or `host -> process.name`. +- `rare_value` means a new value appeared for a profiled entity and field. +- `event_rate_burst`, `auth_failure_burst`, `dns_query_burst`, and + `deny_action_burst` compare the current window to historical buckets. + +The review buttons are part of the detection loop: + +- `Expected`: known behavior that should stay visible but not keep creating + noise for the same scope. +- `False positive`: weak or bad signal for this scoped pattern. +- `Confirmed`: real investigation item. +- Expiry should be used for temporary expected changes, such as maintenance or a + migration window. + ## Primary Workflow: Graylog MCP Graylog 7.1 MCP is the primary log-source integration. In the dashboard, open diff --git a/src/fgai/dashboard.py b/src/fgai/dashboard.py index a46d7be..1746ae2 100644 --- a/src/fgai/dashboard.py +++ b/src/fgai/dashboard.py @@ -45,16 +45,34 @@ HTML = """ SignalScope Monitor

SignalScope Monitor

+
+ +
FortiGate AI/ML Analyzer
@@ -125,11 +163,13 @@ HTML = """
-

Events and Anomalies

Baseline and Stream Health

Correlation Map

AI Assessment

LLM assessment disabled.

Investigation Incidents

Anomalies

Recommendations

+

Events and Anomalies

Baseline and Stream Health

Operator Guidance

Waiting for monitor data.

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.
+

How To Use SignalScope

1. Normal workflow

  1. Settings: connect Graylog MCP and enable streams.
  2. Settings: apply recommended profiles for missing streams.
  3. Diagnostics: confirm raw samples, aggregate counts, and profile readiness.
  4. Overview: use Operator Guidance, incidents, trends, and correlation map.
  5. Findings: review only high-signal deviations first, then mark decisions.

2. Stream health

  • ready: profile exists, events are arriving, and baseline fields are ready.
  • learning: profile exists and events arrive, but baseline age or buckets are still too low.
  • missing_profile: stream is enabled but no profile exists. Apply or edit one.
  • no_events: stream is enabled but the current poll has no raw sample events.
  • partial_fetch: Graylog returned only part of the requested raw sample.

3. Ready fields

0/8 means 8 profile fields are tracked but none are mature enough yet. A field needs at least 12 baseline buckets and the configured Baseline training days before it is ready.

During learning, treat findings as signals to tune profiles, not as final alerts.

4. Profiles

  • Entity fields define who or what behavior is tracked, such as user, host, source IP, or application actor.
  • Baseline fields define the changing behavior to learn, such as action, event ID, service, URL, status, or counters.
  • Relationships learn pairs such as username to srcip or host to process.
  • Detectors add burst checks for auth failures, DNS queries, and deny actions.

5. Findings

  • Start with Triage Queue and incidents, not raw long tables.
  • Open evidence details before confirming a finding.
  • Use Expected for known behavior, False positive for bad signal, Confirmed for real investigation items.
  • Use expiry when a behavior is expected only temporarily.

6. High EPS / MCP

  • Use aggregate or auto fetch mode for high EPS streams.
  • Keep raw samples small enough for context; aggregate counts represent the full window.
  • Sample capped is normal in aggregate mode. Truncated raw mode means you may miss context.
  • If MCP is stale, the UI shows cached status so you can still inspect previous findings.

7. Ollama

  • Dashboard assessment summarizes current evidence.
  • Profile advisor maps unknown/custom fields and suggests relationships.
  • Ollama advice is constrained to fields discovered from Graylog; unknown fields are rejected.

8. What to fix first

  1. No streams enabled.
  2. Enabled streams with missing profiles.
  3. Enabled streams with zero raw events.
  4. Profiles stuck at 0 ready fields after the training window.
  5. Too many repeated findings without review feedback.
+
+