ClearSOC Documentation

Getting Started

ClearSOC is a multi-tenant Security Operations Center platform. It ingests security events from your cloud providers, automatically detects threats using configurable rules, and guides your team through investigation and response — all mapped to the NIST Cybersecurity Framework 2.0.

1. Create your account

Sign up at clearsocapp.com/signup. You'll be walked through company setup (name, domain, industry) and an onboarding wizard that connects your first integration.

2. Connect an integration

Navigate to Integrations and connect at least one cloud provider. ClearSOC connects to 10 event sources; Microsoft 365, Google Workspace and AWS CloudTrail are covered step by step below. A connected integration syncs about every 15 minutes, and its first sync pulls the previous 24 hours.

3. Review your dashboard

After the first sync, your Dashboard will show live event ingestion counts, open incidents, and your NIST CSF 2.0 compliance score. New incidents appear in real-time via WebSocket push — no refresh needed.

Key concepts

Integrations

ClearSOC pulls security events from your sources over OAuth 2.0 or with an API key. Each integration syncs on a recurring schedule and maps raw provider events to a normalized SecurityEvent schema.

Microsoft 365

Covers Entra ID (Azure AD) sign-in logs and the security alerts Microsoft Graph exposes, including Defender for Office 365 email alerts where you license it. The device list feeds your asset inventory. Successful sign-ins are kept with their approximate location, so ClearSOC can flag one person signing in from two places too far apart to travel between.

1. In ClearSOC, go to Integrations → Connect → Microsoft 365.
2. You'll be redirected to the Microsoft OAuth consent screen. Sign in as a Global Administrator. A Security Administrator can connect for detection, but Microsoft refuses Force Password Reset to that role.
3. Grant the requested permissions. Detection reads AuditLog.Read.All and SecurityAlert.Read.All; the response actions use User.ReadWrite.All (disabling a user, revoking sessions), User-PasswordProfile.ReadWrite.All (forcing a password reset, which Microsoft also allows only when the admin who connects holds a role that can reset passwords, such as Global Administrator or User Administrator) and IdentityRiskyUser.ReadWrite.All (marking a user as risky). The asset inventory reads the device list with Device.Read.All. The screen also lists the sign-in scopes openid, profile, email and offline_access.
4. Return to ClearSOC: the integration shows Connected. Its first sync runs on the scheduler's next pass, every five minutes by default, and pulls the previous 24 hours; Sync now starts it straight away.

Google Workspace

Covers the Admin SDK activity reports: sign-ins (including those Google flags as suspicious), admin console changes, Drive activity such as files shared outside your domain, and Gmail forwarding to outside addresses. ChromeOS devices feed your asset inventory.

1. In ClearSOC, go to Integrations → Connect → Google Workspace.
2. Sign in with a Google account that has the Security or Super Admin role.
3. Grant scopes: admin.reports.audit.readonly for detection, and admin.directory.user, which the response actions use to suspend a user or force a password change; admin.directory.device.chromeos.readonly for the ChromeOS devices in your asset inventory; plus the sign-in scopes openid, email and profile.
4. Events appear after the first sync, which runs on the scheduler's next pass and pulls the previous 24 hours.

AWS CloudTrail

Covers management events such as IAM changes, S3 bucket policy changes and EC2 actions, read through CloudTrail's LookupEvents API. Name your trail's S3 bucket and ClearSOC reads the trail's log files instead: every account in an organisation trail, and the data events you choose (S3 object-level activity, for example). Without a bucket, S3 object-level activity is not read.

1. In ClearSOC, go to Integrations → Connect → AWS CloudTrail and open Set up the AWS role. It shows ClearSOC's AWS account ID and your external ID, which is unique to your workspace.
2. In IAM, create a role named ClearSOCIntegration (any name starting with ClearSOC works) with the trust policy shown. It lets ClearSOC's account assume the role only with your external ID.
3. Attach the read policy shown: CloudTrail events, plus your EC2, S3 and RDS inventory. If you want approved response actions to run (disabling an IAM user, revoking its access keys, quarantining an EC2 instance), attach the response policy as well.
4. Paste the role's ARN into the config, with your AWS Region code (for example us-east-2, or several separated by commas), then test and add. ClearSOC always reads us-east-1 as well, where AWS records console sign-ins and IAM changes.
5. Optional: enter your trail's S3 bucket (and prefix, and KMS key if the logs are encrypted) in Set up the AWS role. The read policy then includes listing and reading that bucket, and ClearSOC reads the trail's files rather than LookupEvents.

Jira and Jira Service Management

Connect Jira from the Helpdesk page and choose the project and issue type ClearSOC files issues in. With Jira Service Management, an admin can also have ARGUS answer the service desks you choose:

• It answers how-to questions from your knowledge base, checks the links in a reported phishing email against threat intelligence, and points locked-out people to your self-service reset page.
• It changes an account (signing it out everywhere, and for a leaked password requiring a new one) only after the requester signs in with that account and completes multi-factor authentication.
• Lost MFA devices, access requests and anything on an admin account always go to your team, with ARGUS's summary as an internal note.
• It starts in a 14-day dry run: every reply is an internal note on the request, and nothing changes until you end it.

Sync schedule

A sync that fails is retried with a growing wait, doubling after each failure up to a cap. After an outage, the next good sync asks for everything since the last one, up to seven days back.

Detection Rules

Detection rules define what constitutes a threat. A rule's logic is a JSON object whose type is either threshold or sequence.

Both types match events with a condition: a field, a value and an optional operator. The field is one of event_type, source, actor, source_ip or message; the operator is contains (the default, case-insensitive) or equals.

Threshold rules

Fire an incident when events matching the condition occur N or more times within a time window. Optionally group by source_ip or actor so each IP or user has its own counter.

{
  "type": "threshold",
  "field": "event_type",
  "value": "FailedSignIn",
  "threshold": 10,
  "window_minutes": 5,
  "group_by": "source_ip"
}

This fires when a single IP produces 10 or more FailedSignIn events within 5 minutes, a brute-force pattern.

Sequence rules

Track multi-stage attack patterns. Each stage is one condition with an order. The stages must match in order, for the same user (or IP, with correlate_by), within total_window_minutes.

{
  "type": "sequence",
  "correlate_by": "actor",
  "total_window_minutes": 120,
  "stages": [
    { "order": 1, "field": "event_type", "value": "FailedSignIn" },
    { "order": 2, "field": "event_type", "value": "SuspiciousEmailForward" },
    { "order": 3, "field": "event_type", "value": "ExternalFileShare" }
  ]
}

This fires when the same Google Workspace user fails a sign-in, then forwards mail outside the domain, then shares a Drive file externally, all within two hours.

Rule fields

Rules are created in the app or with POST /api/rules, whose body takes these fields:

Response Actions

ClearSOC executes a response action through the integration that owns the target: Microsoft 365 or Google Workspace for user accounts, Palo Alto NGFW or AWS WAF for IP blocks, CrowdStrike or SentinelOne for hosts, and your AWS account for IAM users and EC2 instances. An action runs when ARGUS takes it on its own, when someone approves it, or when an Analyst or Admin runs it from an incident.

Available actions

Approval flow

When ARGUS proposes an action it may not take on its own, it creates an Approval record instead of executing. Block IP and Isolate Asset always do, at every autonomy level, and so does every action ARGUS proposes on a Critical incident. Approvals expire after 24 hours. Anyone with the Analyst or Admin role can approve or reject from the Approvals page.

Simulation mode

Autonomy levels

Each tenant picks one of 4 autonomy levels. The level sets the highest incident severity ARGUS may act on without a person, and which actions it may take there:

At every level, Block IP and Isolate Asset wait for approval, and ARGUS never acts on its own on a Critical incident. You can also restrict ARGUS to a list of action types; anything outside the list goes to approval.

Compliance Scoring

ClearSOC computes a real-time NIST CSF 2.0 health score (0–100) for your tenant. The overall score is a weighted average of the function scores ClearSOC can actually measure — each reflecting how well you're detecting, responding to, and recovering from threats in that domain. Until a connected data source has synced, there is no score: the posture page says so instead of showing a number.

Function weights

Penalty model

Each open incident deducts points from its function score. The penalty increases with severity and age:

A function ClearSOC is measuring scores 100 while it has nothing open against it. One open Critical incident takes that function to 88, and to 84 once it has been open for more than 72 hours.

What is not scored

A function is measured only when something maps to it: an enabled detection rule, or a recorded incident. A function nothing maps to is reported as not measured — it is left out of the average rather than counted as 100, because no evidence is not the same as a clean result. Identify is currently in that position for every tenant: no ATT&CK tactic maps to it, and asset and vulnerability outcomes are not scored yet. The posture page and the exports show which functions were measured and what share of the framework, by weight, the overall score covers.

SLA thresholds

ClearSOC tracks SLA compliance on resolved incidents:

Coverage gaps

If neither an enabled detection rule nor any incident covers a NIST function, each of that function's reference categories is listed as a coverage gap on the Compliance page, with a suggested next step.

Incident evidence pack

An admin or an auditor can download one incident as a zip from its page, to hand to an auditor, an insurer or a regulator. It holds four files: report.pdf, the incident told in order; record.json, its stored record: the detection rule, the assessment, ARGUS decisions, the response actions, the approvals, linked tickets, notes and the audit trail, each value as it was stored; events.csv, its events; and manifest.json, the SHA-256 digest of each of the other three. Every export writes the manifest's digest to your audit log, so a pack can be checked later against that entry. The audit trail in the pack leaves out the IP address and browser of the people in it, and an incident with more events than a pack carries says so in every file. The pack is a compliance export, like the insurance-readiness PDF.

API Reference

All API endpoints are under https://clearsocapp.com/api. Authentication uses a JWT stored in an httpOnly cookie (clearsoc_access), refreshed automatically via a separate refresh token cookie. Its lifetime is your tenant's session timeout capped at 2 hours.

Authentication

POST /api/auth/login
Content-Type: application/json

{ "email": "you@company.com", "password": "your-password" }

→ 200 OK  (sets clearsoc_access + clearsoc_refresh cookies)
{ "user": { "id": "...", "email": "...", "role": "admin", "tenantId": "..." } }

POST /api/auth/refresh   → refreshes access token using refresh cookie
POST /api/auth/logout    → revokes refresh token, clears cookies

If the account uses MFA, the login response is { "mfaRequired": true } instead, and POST /api/auth/mfa/verify issues the session once the code checks out.

Events ingestion

Push events from any source with an ingest key, created on the API Keys page. The key decides the tenant, so the body carries no tenant ID.

POST /api/events
X-Api-Key: csk_…
Idempotency-Key: 7d2c9e41-…   (optional)
Content-Type: application/json

{
  "events": [
    {
      "source":     "crowdstrike",
      "eventType":  "ProcessBlocked",
      "severity":   "High",
      "message":    "Malicious process blocked on WORKSTATION-01",
      "rawData":    { "processName": "mimikatz.exe", "pid": 4821 },
      "occurredAt": "2026-05-09T12:00:00Z"
    }
  ]
}

→ 200 OK  { "ingested": 1, "usedToday": …, "capPerDay": … }

Up to 5,000 events per request. A batch that would pass your plan's daily cap is refused whole, with 429 and a Retry-After that points at midnight UTC. Resending with the same Idempotency-Key replays the first response instead of ingesting twice.

Key endpoints

Rate limits

Exceeded limits return 429 Too Many Requests with a Retry-After header.