Documentation

ClearSOC is an AI-assisted security operations platform for Akamai WAF telemetry. It brings traffic exploration, entity analysis, response decisions, and historical reporting into one workspace.

The dashboard presents stored observations and job results. Its animations and status labels do not establish that an analysis is running right now. Check timestamps and the selected time window before interpreting activity.

1. Read the recorded posture. Open the command center. Note the mode, last scenario, and last AI decision. Refresh if the page has been open for a while.
2. Set the scope. In Analysis, choose the hostname and time window. Keep those values with your investigation notes.
3. Review the queue. Open AI Decisions and filter by entity type, state, severity, confidence, or hostname.
4. Inspect evidence. Open an entity’s investigation. Compare its activity with the scenario and AI rationale before choosing an action.
5. Verify the outcome. Separate the local decision from the provider update and activation. Carry unresolved enforcement or evidence gaps into the handoff.

Unexpectedly quiet workspace? Check telemetry and job recency before concluding that the environment is quiet.

The layers serve different purposes. First-level analysis prepares entity evidence; it is not a separate language-model opinion.

Jobs run on schedules. Mode gating, run limits, feature switches, and retry timing can prevent an AI call. The diagram describes the logical flow, not a guarantee that every request reaches all three layers.

The dashboard combines an intelligence core, operational briefing, three analysis links, a traffic pulse, and a chronological activity timeline.

Traffic metrics carry a time window and hostname scope. The current watchlist is labeled as all-host state. The timeline contains recent recorded events; it is not a streaming connection. Use Refresh to retrieve a new snapshot.

Use Analysis to compare traffic patterns, inspect paths and sources, and narrow a hypothesis. Begin with a hostname and time window, then examine request volumes alongside WAF signals.

• A flag is evidence to examine. WAF alerts and denies are provider signals, not ground-truth maliciousness labels.
• Alert and deny counts can overlap. One request may contain both kinds of signals. Do not automatically add them to estimate unique requests.
• Distinct rules are not request counts. An entity’s unique rule list describes variety; request totals describe volume.
• Rate needs a window. A large daily total alone does not establish a short burst.

Geography, ASN, and a TLS fingerprint provide context. They do not uniquely identify a person or prove intent. Keep the entity’s own paths, counts, rule matches, and timing central to the review.

AI Decisions is the review queue. Model recommendations can be changed by policy before the final local state is recorded.

How automated recommendations are constrained

Policy considers advisory versus enforce mode, confidence thresholds, non-IP blocking permissions, scenario requirements, and review requirements for ASN or TLS actions. Inspect the model action, final action, and policy explanation when a recommendation was downgraded.

What provider status establishes

Akamai integration appends entries to configured Client Lists and can request activation. appended or already_present describes list membership. An activation response alone does not verify completed propagation or that a policy is using that list. Confirm the intended network and provider-side result.

disabled means external blocking was not enabled; failed means the provider operation failed. A local blocklist row can still exist in either case. Conversely, changing an entity to watchlist or removing it locally does not automatically remove an existing Akamai Client List entry in the current implementation.

Open an entity from the decisions queue to reach its Investigation Workspace. Review its current state, AI rationale, traffic context, and related activity together.

1. Confirm the entity type: an IP, an ASN, or a TLS fingerprint.
2. Check last-seen time and the period represented by the evidence.
3. Compare flagged requests with total requests; inspect paths and matched rules.
4. Look for corroborating evidence and plausible legitimate activity.
5. Choose the narrowest justified action, then verify local and external outcomes separately.

Manual actions require the Trigger actions permission. They are analyst overrides, not a new automatic AI policy evaluation. Review any provider changes independently, including when automated mitigation is advisory.

Security Analysis provides the redesigned report reader. Reports remains available as the existing reporting workspace.

• Choose Daily, Weekly, or Monthly, then select an entry in the report archive.
• Check both the covered time range and generated timestamp. Reports are historical, not live incident status.
• Read the narrative alongside period facts, scenario triggers, and security events.
• Use In this report on desktop to jump to narrative headings and supporting evidence.
• Use Download summary to save the narrative as Markdown. This download is not an export of all telemetry or side-panel evidence.

The reader currently offers the latest ten summaries per cadence. Supporting event lists are limited previews. When totals and narrative appear inconsistent, compare the covered dates and source records; some metrics can fall back to values parsed from the generated report when telemetry values are unavailable or zero.

Unavailable or N/A means a value is missing. Do not treat it as zero. Narrative text remains readable if formatting scripts are unavailable.

The AI Assistant plans queries using approved read-only tools for traffic, paths, attackers, entity profiles, blocklist state, and comparisons. It does not execute arbitrary SQL or perform mitigation actions through chat.

Include the hostname, entity, and time window in the question. Do not assume filters selected on another page carry into chat. Review the answer’s time scope and compare important claims with the underlying investigation.

Attack Scenarios defines traffic type/subtype, action scope, optional hostname and paths, count window, threshold, severity, and timing settings.

The current evaluator uses matching request count ≥ configured threshold. P1 maps to attack mode; P2 and P3 map to elevated mode. Names such as “ratio spike” do not mean a statistical baseline or ratio comparison is being calculated.

Eligibility is not a guarantee of execution: feature switches, hourly limits, retry timing, and candidate availability also apply. First-level staging can be skipped in baseline mode when heavy AI is gated.

Admin controls integrations, AI models, mitigation policy, reporting, and job settings. Prompts contains workflow instructions; Advanced exposes additional operational controls.

Use the scope shown beside the setting. Record what changed and compare the next applicable run with the intended result. Test prompt changes against representative benign and malicious examples before depending on them for automated decisions.

Provider credentials are configured through supported integration settings or the deployment environment. Keep credentials out of reports, chat prompts, and incident notes.

Notifications supports Slack and Discord webhooks. Destinations can select scenario, entity, approval-request, and summary events, with filters and suppression controls.

1. Confirm the destination is enabled and the event type is selected.
2. Check severity, confidence, and other routing filters.
3. Check suppression or deduplication before treating a missing message as a delivery failure.
4. Review delivery records. Use the test action only when you intend to send a message to the configured destination.

A delivered notification proves delivery to the channel, not completed enforcement. An approval-request event should be followed through the review workflow; it is not proof an action was approved.

AI Operations records model task execution, timing, request sizes, and errors. Use it to establish whether an analysis ran and whether the provider call succeeded.

AI Efficiency provides operational metrics for decisions and traffic around them. Review the selected period and grace window before drawing conclusions.

The mitigation worker can defer retries after transient provider failures. A quiet task log can also result from mode gating or no eligible candidates; it does not automatically imply a service outage.

The permission matrix below is generated from the application’s role definitions, so it follows the current access model.

Admins manage accounts in Users and review changes in Activity. All roles can view the admin interface, but access to individual operations is permission-controlled. A hidden or denied action may be expected for your role.

Administrative history, security decision events, and external enforcement records answer different questions. Correlate their entity and timestamps when reconstructing an action.

• Queue exports: download the AI decisions CSV or entity blocklist CSV. These links request unfiltered exports.
• Summary download: use Security Analysis to download the selected narrative as Markdown.
• Data inspection: use Tables for supporting records when the operational views do not answer a question.

For every export, record the selected filters and generation time. A current-state list and a historical event log will not have the same row count.

A concise handoff makes the next operator’s review faster. Capture the following alongside the relevant entity or report link:

• Scope: hostname, entity type/value, and UTC time window.
• Observation: request counts, rule matches, paths, and what changed.
• Interpretation: suspected behavior, confidence limits, and benign alternatives.
• Decision: AI recommendation, policy adjustment, and any analyst override.
• Outcome: local state, provider result, activation network, and verification still needed.
• Next review: owner, open question, and when to check again.

Use historical reports for context and handoff. Recheck recent telemetry before making a decision about current activity.

Entity

An IP, ASN, or TLS fingerprint used to aggregate observations and decisions.

ASN

An autonomous system number associated with a network. It can cover many unrelated users and applications.

TLS fingerprint

A representation of TLS client handshake characteristics. Multiple clients can share it; it is not a certificate.

Watchlist

Local state marking an entity for review. Presence alone does not prove that it has been reevaluated recently.

Alert-bearing request

A request with one or more WAF alert signals. It may also carry deny signals.

Deny-bearing request

A request with one or more provider deny signals. This is distinct from a ClearSOC block recommendation.

Monitoring mode

Recorded baseline, elevated, or attack posture derived from scenarios and cooldown state.

Advisory / enforce

Automated mitigation policy modes. Advisory downgrades model block recommendations; enforce permits them when other policy checks pass.

Confidence

A model-supplied judgment, not a calibrated accuracy metric.

External enforcement

The provider-side update and its effective application, which must be distinguished from local list state.

Current state / event history

Current state shows the effective latest record. Event history records changes over time and can contain multiple events for one entity.