Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat: Tailscale connector + AWS GuardDuty credential-exfiltration Sigma rule

Beenu Arorac974cb8b83ed
diff --git a/apps/docs/docs/connectors/tailscale.md b/apps/docs/docs/connectors/tailscale.md
new file mode 100644
index 000000000..71d3fcad2
--- /dev/null
+++ b/apps/docs/docs/connectors/tailscale.md
@@ -0,0 +1,98 @@
+---
+sidebar_position: 11
+title: Tailscale
+description: Zero-trust network audit logs from Tailscale into AiSOC — ACL changes, device approvals, key rotations, and more.
+---
+
+# Tailscale
+
+The Tailscale connector pulls administrative audit logs from your tailnet via the [Tailscale API v2](https://tailscale.com/api).
+
+Two conceptual streams are ingested:
+
+1. **Administrative audit log** — every action taken in the admin console or via the API: ACL/policy changes, device approvals and removals, key rotations, user role and tag changes, subnet router and exit-node approvals, OIDC/SAML configuration mutations, DNS updates, and webhook CRUD operations.
+2. **ACL policy diff events** — `acl:update` events are surfaced at **HIGH** severity because ACL changes are a common lateral-movement enabler in zero-trust networks.
+
+Events are normalized with `source: tailscale`, `category: network`.
+
+## Prerequisites
+
+- A **Tailscale organization** account (Starter, Premium, or Enterprise). The audit log API is available on all paid plans; the free personal plan may have limited history.
+- One of the following authentication options:
+ - **API key** (starts with `tskey-api-`): simplest for development and small deployments. Long-lived; revoke and rotate via the Tailscale admin console.
+ - **OAuth 2.0 client credentials** (client ID + client secret): preferred for production. Grants a short-lived, auto-refreshed token. Requires the `audit:read` OAuth scope.
+
+## Setup walkthrough
+
+### Option A — API Key
+
+1. Go to **Tailscale admin console → Settings → Keys**.
+2. Click **Generate API key**.
+3. Copy the key (it starts with `tskey-api-…`) — you will not be able to see it again.
+4. In AiSOC, go to **Connectors → Add connector → Tailscale**.
+5. Fill in:
+ - **Tailnet**: your organisation slug or email (e.g. `example.com`). Use `-` to auto-detect from the key.
+ - **API Key**: paste the key.
+6. Click **Test connection**, then **Save**.
+
+### Option B — OAuth Client Credentials (production)
+
+1. Go to **Tailscale admin console → Settings → OAuth clients**.
+2. Click **Generate OAuth client**.
+3. Grant the **`audit:read`** scope.
+4. Copy the **Client ID** and **Client Secret**.
+5. In AiSOC, go to **Connectors → Add connector → Tailscale**.
+6. Fill in:
+ - **Tailnet**: your organisation slug.
+ - **OAuth Client ID**: paste the client ID.
+ - **OAuth Client Secret**: paste the secret (stored encrypted in the credential vault).
+7. Click **Test connection**, then **Save**.
+
+The connector automatically refreshes the access token before expiry — no manual rotation required.
+
+## Polling details
+
+- Default interval: **300 seconds**.
+- Per poll, the connector calls `GET /api/v2/tailnet/{tailnet}/audit?startTime=<lastpoll>` with cursor-based pagination.
+- The `startTime` parameter is set to `now() - poll_interval` on each run. For the very first run, the connector looks back 5 minutes.
+- Cursor pagination continues until no `nextCursor` is returned, ensuring no events are dropped between polls.
+
+## Severity heuristics
+
+| Action | Severity |
+|---|---|
+| `acl:update` — policy/ACL file modified | `high` |
+| `acl:delete` | `high` |
+| `device:approve`, `device:delete`, `device:expire_key` | `high` |
+| `routes:approve`, `routes:set_advertised` | `high` |
+| `auth_key:create`, `auth_key:delete` | `high` |
+| `user:invite`, `user:delete`, `user:role_update` | `high` |
+| `oidc:update`, `saml:update` | `high` |
+| `tailnet:transfer_ownership`, `tailnet:delete` | `high` |
+| `webhook:create`, `webhook:update`, `webhook:delete` | `high` |
+| `settings:update`, `logging:set_config` | `high` |
+| `device:update`, `tag:update` | `medium` |
+| `posture:create`, `posture:update`, `posture:delete` | `medium` |
+| Any `*:delete` or `*:remove` not already mapped | `medium` |
+| Everything else | `info` |
+
+## Troubleshooting
+
+**`403 Forbidden` on audit endpoint** — the token or OAuth client is missing the `audit:read` scope. Create a new API key / OAuth client with the correct scope; you cannot patch scopes on an existing credential.
+
+**Empty results** — the selected tailnet name may be incorrect. Try using `-` to auto-resolve from the token, then update the tailnet field to the resolved name shown in test-connection output.
+
+**OAuth token refresh errors** — verify that the client secret has not been revoked in the Tailscale admin console. Re-generate and update the connector config.
+
+**Short audit log history** — Tailscale retains audit logs according to your plan's data retention policy. Events older than the retention window will not appear regardless of the `startTime` value sent.
+
+## False positives
+
+- Misconfigured CI/CD runners that trigger ACL validation via the Tailscale CLI.
+- Automated key rotation scripts that cycle `auth_key` or `tailnet_key` on a schedule.
+- Red-team / penetration tests: ensure exercises are documented in the change management system and acknowledged as false positives in AiSOC.
+
+## Related
+
+- [GitHub Audit + Code Scanning](/docs/connectors/github) — for VCS-side changes that may accompany infrastructure ACL updates.
+- [Cloudflare](/docs/connectors/cloudflare) — for edge network policy changes on the same zero-trust surface.
diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.ts
index 9486308ce..c0f835960 100644
--- a/apps/docs/sidebars.ts
+++ b/apps/docs/sidebars.ts
@@ -26,6 +26,7 @@ const sidebars: SidebarsConfig = {
"connectors/google-workspace",
"connectors/cloudflare",
"connectors/github",
+ "connectors/tailscale",
],
},
{
diff --git a/apps/web/public/marketplace/index.json b/apps/web/public/marketplace/index.json
index 312cee107..29c2f82ad 100644
--- a/apps/web/public/marketplace/index.json
+++ b/apps/web/public/marketplace/index.json
@@ -1,7 +1,7 @@
{
"$schema": "https://aisoc.dev/schemas/marketplace/v1.json",
"version": "1.0.0",
- "generated": "2026-05-05T22:11:19Z",
+ "generated": "2026-05-06T08:25:33Z",
"categories": [
{
"id": "playbooks",
@@ -20,19 +20,20 @@
}
],
"stats": {
- "total": 6987,
+ "total": 6989,
"playbooks": 50,
- "detections": 6913,
- "plugins": 24,
- "verified": 874,
+ "detections": 6914,
+ "plugins": 25,
+ "verified": 875,
"community": 0,
"by_tier": {
+ "beta": 1,
"imported": 6113,
- "stable": 874
+ "stable": 875
},
"detections_by_tier": {
"imported": 6113,
- "stable": 800
+ "stable": 801
},
"quarantined": 5937
},
@@ -152,7 +153,7 @@
"T1070.006": 6,
"T1070.008": 7,
"T1071": 12,
- "T1071.001": 53,
+ "T1071.001": 54,
"T1071.002": 1,
"T1071.003": 3,
"T1071.004": 23,
@@ -163,7 +164,7 @@
"T1078.001": 10,
"T1078.002": 14,
"T1078.003": 11,
- "T1078.004": 91,
+ "T1078.004": 92,
"T1082": 49,
"T1083": 28,
"T1087": 21,
@@ -372,7 +373,7 @@
"T1552.002": 7,
"T1552.003": 3,
"T1552.004": 14,
- "T1552.005": 2,
+ "T1552.005": 3,
"T1552.006": 7,
"T1552.007": 9,
"T1553": 4,
@@ -531,7 +532,7 @@
"T1690": 1
},
"unique_techniques": 491,
- "total_with_mitre": 5710,
+ "total_with_mitre": 5711,
"by_tier": {
"stable": {
"T1003": 2,
@@ -576,14 +577,14 @@
"T1070.002": 1,
"T1070.003": 2,
"T1071": 2,
- "T1071.001": 9,
+ "T1071.001": 10,
"T1071.004": 5,
"T1074.001": 1,
"T1078": 35,
"T1078.001": 4,
"T1078.002": 3,
"T1078.003": 1,
- "T1078.004": 32,
+ "T1078.004": 33,
"T1083": 2,
"T1087.001": 2,
"T1087.002": 5,
@@ -683,7 +684,7 @@
"T1552": 1,
"T1552.001": 12,
"T1552.004": 2,
- "T1552.005": 1,
+ "T1552.005": 2,
"T1552.007": 1,
"T1553": 1,
"T1553.001": 4,
@@ -34400,6 +34401,31 @@
"enabled": true,
"path": "detections/cloud/cloud-org-rootmail-modified.yaml"
},
+ {
+ "id": "det-cloud-191",
+ "type": "detection",
+ "name": "AWS GuardDuty \u2014 UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration",
+ "description": "Detects GuardDuty HIGH-severity finding that EC2 instance credentials (obtained via the IMDS) were used from an IP address outside of AWS \u2014 a strong signal of instance metadata theft and subsequent exfiltration of the temporary credentials to an attacker-controlled host. GuardDuty generates this when the calling IP is publicly routable and does not belong to the originating EC2 instance's region.",
+ "version": "1.0.0",
+ "author": "AiSOC",
+ "tags": [
+ "tlp.white"
+ ],
+ "severity": "critical",
+ "category": "cloud",
+ "mitre_techniques": [
+ "T1552.005",
+ "T1078.004",
+ "T1071.001"
+ ],
+ "log_source": "aws",
+ "playbook": "tpl-credential-access",
+ "verified": true,
+ "source": "core",
+ "tier": "stable",
+ "enabled": true,
+ "path": "detections/cloud/aws-guardduty-instance-credential-exfiltration.yaml"
+ },
{
"id": "det-data-exfil-001",
"type": "detection",
@@ -222184,6 +222210,32 @@
"tier": "stable",
"path": "plugins/tailscale-acl/plugin.yaml"
},
+ {
+ "id": "tailscale-connector",
+ "type": "plugin",
+ "name": "Tailscale Connector",
+ "description": "Tailscale zero-trust network audit log connector. Ingests every administrative action from your tailnet: ACL/policy changes, device approvals and removals, key rotations, user role changes, exit-node and subnet-router updates, OIDC/SAML configuration mutations, and more. Supports both long-lived API keys and OAuth 2.0 client-credential flow for production deployments.",
+ "version": "1.0.0",
+ "author": "AiSOC Core Team",
+ "tags": [
+ "network",
+ "zero-trust",
+ "vpn",
+ "tailscale",
+ "audit",
+ "iam"
+ ],
+ "plugin_type": "connector",
+ "license": "MIT",
+ "homepage": "https://github.com/beenuar/AiSOC/tree/main/plugins/tailscale-connector",
+ "min_aisoc_version": "4.0.0",
+ "sdks": [],
+ "mitre_techniques": [],
+ "verified": false,
+ "source": "core",
+ "tier": "beta",
+ "path": "plugins/tailscale-connector/plugin.yaml"
+ },
{
"id": "twilio-sms",
"type": "plugin",
diff --git a/detections/cloud/aws-guardduty-instance-credential-exfiltration.yaml b/detections/cloud/aws-guardduty-instance-credential-exfiltration.yaml
new file mode 100644
index 000000000..5052dda65
--- /dev/null
+++ b/detections/cloud/aws-guardduty-instance-credential-exfiltration.yaml
@@ -0,0 +1,41 @@
+id: det-cloud-191
+name: AWS GuardDuty — UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration
+description: >
+ Detects GuardDuty HIGH-severity finding that EC2 instance credentials (obtained via
+ the IMDS) were used from an IP address outside of AWS — a strong signal of instance
+ metadata theft and subsequent exfiltration of the temporary credentials to an
+ attacker-controlled host. GuardDuty generates this when the calling IP is publicly
+ routable and does not belong to the originating EC2 instance's region.
+version: 1.0.0
+severity: critical
+tags:
+ - mitre.attack.t1552.005 # Unsecured Credentials: Cloud Instance Metadata API
+ - mitre.attack.t1078.004 # Valid Accounts: Cloud Accounts
+ - mitre.attack.t1071.001 # Application Layer Protocol: Web Protocols
+ - tlp.white
+category: cloud
+log_source:
+ product: aws
+ service: guardduty
+detection:
+ # GuardDuty findings arrive via EventBridge (default) or SNS.
+ # The finding type string is stable — match on the canonical name.
+ condition: |
+ finding_type == "UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration.OutsideAWS"
+ OR (
+ finding_type STARTSWITH "UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration"
+ AND finding_severity >= 7.0
+ )
+false_positives:
+ - Misconfigured CI/CD runner that pulls instance-role creds and runs from a non-AWS IP
+ - Lambda extension or custom exporter forwarding metrics from outside the originating region
+ - Legitimate cross-region forwarding via a NAT device in a different AWS region
+ - Penetration test or red-team exercise documented in the change management system
+references:
+ - https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_finding-types-iam.html#unauthorizedaccess-iam-instancecredentialexfiltrationoutsideaws
+ - https://attack.mitre.org/techniques/T1552/005/
+playbook: tpl-credential-access
+enabled: true
+author: AiSOC
+created: '2026-05-06'
+modified: '2026-05-06'
diff --git a/marketplace/index.json b/marketplace/index.json
index 312cee107..29c2f82ad 100644
--- a/marketplace/index.json
+++ b/marketplace/index.json
@@ -1,7 +1,7 @@
{
"$schema": "https://aisoc.dev/schemas/marketplace/v1.json",
"version": "1.0.0",
- "generated": "2026-05-05T22:11:19Z",
+ "generated": "2026-05-06T08:25:33Z",
"categories": [
{
"id": "playbooks",
@@ -20,19 +20,20 @@
}
],
"stats": {
- "total": 6987,
+ "total": 6989,
"playbooks": 50,
- "detections": 6913,
- "plugins": 24,
- "verified": 874,
+ "detections": 6914,
+ "plugins": 25,
+ "verified": 875,
"community": 0,
"by_tier": {
+ "beta": 1,
"imported": 6113,
- "stable": 874
+ "stable": 875
},
"detections_by_tier": {
"imported": 6113,
- "stable": 800
+ "stable": 801
},
"quarantined": 5937
},
@@ -152,7 +153,7 @@
"T1070.006": 6,
"T1070.008": 7,
"T1071": 12,
- "T1071.001": 53,
+ "T1071.001": 54,
"T1071.002": 1,
"T1071.003": 3,
"T1071.004": 23,
@@ -163,7 +164,7 @@
"T1078.001": 10,
"T1078.002": 14,
"T1078.003": 11,
- "T1078.004": 91,
+ "T1078.004": 92,
"T1082": 49,
"T1083": 28,
"T1087": 21,
@@ -372,7 +373,7 @@
"T1552.002": 7,
"T1552.003": 3,
"T1552.004": 14,
- "T1552.005": 2,
+ "T1552.005": 3,
"T1552.006": 7,
"T1552.007": 9,
"T1553": 4,
@@ -531,7 +532,7 @@
"T1690": 1
},
"unique_techniques": 491,
- "total_with_mitre": 5710,
+ "total_with_mitre": 5711,
"by_tier": {
"stable": {
"T1003": 2,
@@ -576,14 +577,14 @@
"T1070.002": 1,
"T1070.003": 2,
"T1071": 2,
- "T1071.001": 9,
+ "T1071.001": 10,
"T1071.004": 5,
"T1074.001": 1,
"T1078": 35,
"T1078.001": 4,
"T1078.002": 3,
"T1078.003": 1,
- "T1078.004": 32,
+ "T1078.004": 33,
"T1083": 2,
"T1087.001": 2,
"T1087.002": 5,
@@ -683,7 +684,7 @@
"T1552": 1,
"T1552.001": 12,
"T1552.004": 2,
- "T1552.005": 1,
+ "T1552.005": 2,
"T1552.007": 1,
"T1553": 1,
"T1553.001": 4,
@@ -34400,6 +34401,31 @@
"enabled": true,
"path": "detections/cloud/cloud-org-rootmail-modified.yaml"
},
+ {
+ "id": "det-cloud-191",
+ "type": "detection",
+ "name": "AWS GuardDuty \u2014 UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration",
+ "description": "Detects GuardDuty HIGH-severity finding that EC2 instance credentials (obtained via the IMDS) were used from an IP address outside of AWS \u2014 a strong signal of instance metadata theft and subsequent exfiltration of the temporary credentials to an attacker-controlled host. GuardDuty generates this when the calling IP is publicly routable and does not belong to the originating EC2 instance's region.",
+ "version": "1.0.0",
+ "author": "AiSOC",
+ "tags": [
+ "tlp.white"
+ ],
+ "severity": "critical",
+ "category": "cloud",
+ "mitre_techniques": [
+ "T1552.005",
+ "T1078.004",
+ "T1071.001"
+ ],
+ "log_source": "aws",
+ "playbook": "tpl-credential-access",
+ "verified": true,
+ "source": "core",
+ "tier": "stable",
+ "enabled": true,
+ "path": "detections/cloud/aws-guardduty-instance-credential-exfiltration.yaml"
+ },
{
"id": "det-data-exfil-001",
"type": "detection",
@@ -222184,6 +222210,32 @@
"tier": "stable",
"path": "plugins/tailscale-acl/plugin.yaml"
},
+ {
+ "id": "tailscale-connector",
+ "type": "plugin",
+ "name": "Tailscale Connector",
+ "description": "Tailscale zero-trust network audit log connector. Ingests every administrative action from your tailnet: ACL/policy changes, device approvals and removals, key rotations, user role changes, exit-node and subnet-router updates, OIDC/SAML configuration mutations, and more. Supports both long-lived API keys and OAuth 2.0 client-credential flow for production deployments.",
+ "version": "1.0.0",
+ "author": "AiSOC Core Team",
+ "tags": [
+ "network",
+ "zero-trust",
+ "vpn",
+ "tailscale",
+ "audit",
+ "iam"
+ ],
+ "plugin_type": "connector",
+ "license": "MIT",
+ "homepage": "https://github.com/beenuar/AiSOC/tree/main/plugins/tailscale-connector",
+ "min_aisoc_version": "4.0.0",
+ "sdks": [],
+ "mitre_techniques": [],
+ "verified": false,
+ "source": "core",
+ "tier": "beta",
+ "path": "plugins/tailscale-connector/plugin.yaml"
+ },
{
"id": "twilio-sms",
"type": "plugin",
diff --git a/plugins/tailscale-connector/plugin.yaml b/plugins/tailscale-connector/plugin.yaml
new file mode 100644
index 000000000..79e28f225
--- /dev/null
+++ b/plugins/tailscale-connector/plugin.yaml
@@ -0,0 +1,45 @@
+id: tailscale-connector
+name: Tailscale Connector
+version: "1.0.0"
+plugin_type: connector
+description: >
+ Tailscale zero-trust network audit log connector.
+ Ingests every administrative action from your tailnet: ACL/policy changes,
+ device approvals and removals, key rotations, user role changes, exit-node
+ and subnet-router updates, OIDC/SAML configuration mutations, and more.
+ Supports both long-lived API keys and OAuth 2.0 client-credential flow for
+ production deployments.
+author: AiSOC Core Team
+tags:
+ - network
+ - zero-trust
+ - vpn
+ - tailscale
+ - audit
+ - iam
+homepage: https://github.com/beenuar/AiSOC/tree/main/plugins/tailscale-connector
+license: MIT
+min_aisoc_version: "4.0.0"
+config_schema:
+ type: object
+ required: [tailnet]
+ properties:
+ tailnet:
+ type: string
+ description: >
+ Your tailnet name (organisation slug or email address shown in the
+ Tailscale admin console). Use '-' to use the default tailnet of the
+ authenticated token.
+ api_key:
+ type: string
+ description: >
+ Tailscale API key (starts with 'tskey-api-').
+ Use this *or* the OAuth client credentials below — not both.
+ secret: true
+ client_id:
+ type: string
+ description: OAuth 2.0 client ID (from the Tailscale admin console).
+ client_secret:
+ type: string
+ description: OAuth 2.0 client secret.
+ secret: true
diff --git a/services/connectors/app/connectors/__init__.py b/services/connectors/app/connectors/__init__.py
index d2db8e02b..8fb6d484f 100644
--- a/services/connectors/app/connectors/__init__.py
+++ b/services/connectors/app/connectors/__init__.py
@@ -32,6 +32,7 @@ from app.connectors.m365_audit import M365AuditConnector
from app.connectors.microsoft_sentinel import MicrosoftSentinelConnector
from app.connectors.okta import OktaConnector
from app.connectors.splunk import SplunkConnector
+from app.connectors.tailscale import TailscaleConnector
if TYPE_CHECKING:
pass
@@ -55,6 +56,7 @@ _CONNECTOR_CLASSES: tuple[type[BaseConnector], ...] = (
MicrosoftSentinelConnector,
OktaConnector,
SplunkConnector,
+ TailscaleConnector,
)
@@ -108,6 +110,7 @@ __all__ = [
"OAuthHints",
"OktaConnector",
"SplunkConnector",
+ "TailscaleConnector",
"get_connector_class",
"list_connector_schemas",
]
diff --git a/services/connectors/app/connectors/tailscale.py b/services/connectors/app/connectors/tailscale.py
new file mode 100644
index 000000000..7f9f2f431
--- /dev/null
+++ b/services/connectors/app/connectors/tailscale.py
@@ -0,0 +1,346 @@
+"""
+Tailscale audit log connector.
+
+Pulls two event streams from the Tailscale API v2:
+
+1. **Audit logs** — ``GET /tailnet/{tailnet}/audit``
+ Every administrative action: ACL changes, device approvals/removals, key
+ rotations, user role changes, subnet router and exit-node changes, OIDC /
+ SAML configuration mutations, etc. Requires the ``audit:read`` OAuth scope.
+
+2. **Policy file changes** — embedded inside audit events with
+ ``action == "acl:update"``; no separate endpoint. We surface these
+ at HIGH severity because ACL changes are a common lateral-movement
+ enabler in zero-trust networks.
+
+Auth: Tailscale supports two auth methods:
+ * **API key** (long-lived, starts with ``tskey-api-``): simplest for testing
+ and small deployments.
+ * **OAuth client credential** (client_id + client_secret): preferred for
+ production. The connector accepts either style — if ``client_id`` and
+ ``client_secret`` are both provided, it performs the client-credentials
+ flow automatically and refreshes the token before expiry.
+
+Tailnet: the organisational identifier. For personal accounts this is the
+email address (``[email protected]``). For organisations it is the custom
+short-name shown in the admin panel, or ``-`` to use the default tailnet of
+the authenticated token.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+import structlog
+
+from app.connectors.base import BaseConnector, ConnectorSchema, Field, OAuthHints
+
+logger = structlog.get_logger()
+
+_BASE = "https://api.tailscale.com/api/v2"
+
+# Audit event actions that we treat as HIGH severity. These are either
+# reversible-but-dangerous changes that could be used for persistence /
+# lateral movement, or irreversible destructive operations.
+_HIGH_SEVERITY_ACTIONS = frozenset(
+ {
+ # ACL / policy
+ "acl:update",
+ "acl:delete",
+ # Device management
+ "device:approve",
+ "device:delete",
+ "device:expire_key",
+ "device:update_authorized",
+ # Exit nodes and subnet routers
+ "routes:set_advertised",
+ "routes:approve",
+ "routes:disapprove",
+ # Key management
+ "auth_key:create",
+ "auth_key:delete",
+ "tailnet_key:create",
+ "tailnet_key:delete",
+ # Users / roles
+ "user:invite",
+ "user:delete",
+ "user:approve",
+ "user:role_update",
+ "user:restore",
+ # Identity provider / OIDC
+ "oidc:update",
+ "saml:update",
+ # DNS / MagicDNS
+ "dns:update",
+ # Admin
+ "tailnet:transfer_ownership",
+ "tailnet:delete",
+ "settings:update",
+ "logging:set_config",
+ # Webhooks (could be abused as C2 notification channel)
+ "webhook:create",
+ "webhook:update",
+ "webhook:delete",
+ }
+)
+
+_MEDIUM_SEVERITY_ACTIONS = frozenset(
+ {
+ "device:update",
+ "tag:update",
+ "acl:validate",
+ "posture:create",
+ "posture:update",
+ "posture:delete",
+ }
+)
+
+
+class TailscaleConnector(BaseConnector):
+ """Tailscale audit log connector."""
+
+ connector_id = "tailscale"
+ connector_name = "Tailscale"
+ connector_category = "network"
+
+ @classmethod
+ def schema(cls) -> ConnectorSchema:
+ return ConnectorSchema(
+ connector_id=cls.connector_id,
+ connector_name=cls.connector_name,
+ category=cls.connector_category,
+ description=(
+ "Tailscale zero-trust network audit logs. "
+ "Captures every ACL change, device approval / removal, key rotation, "
+ "user role change, and admin configuration mutation in your tailnet."
+ ),
+ docs_url="/docs/connectors/tailscale",
+ fields=[
+ Field(
+ "tailnet",
+ "string",
+ "Tailnet",
+ placeholder="example.com or -",
+ help_text=(
+ "Your tailnet name (the organisation slug shown in the Tailscale "
+ "admin console, e.g. 'example.com'). Use '-' to use the default "
+ "tailnet associated with the API key / OAuth token."
+ ),
+ ),
+ Field(
+ "api_key",
+ "secret",
+ "API Key (optional if using OAuth)",
+ required=False,
+ help_text=(
+ "Tailscale API key (starts with 'tskey-api-'). "
+ "Use either this *or* the OAuth client credentials below — not both."
+ ),
+ ),
+ Field(
+ "client_id",
+ "string",
+ "OAuth Client ID (optional)",
+ required=False,
+ help_text=(
+ "OAuth 2.0 client ID from the Tailscale admin console. "
+ "Required scope: 'audit:read'."
+ ),
+ ),
+ Field(
+ "client_secret",
+ "secret",
+ "OAuth Client Secret (optional)",
+ required=False,
+ help_text=(
+ "OAuth 2.0 client secret. "
+ "Only needed when using client-credential flow instead of an API key."
+ ),
+ ),
+ ],
+ oauth=OAuthHints(
+ supported_in_hosted=False,
+ authorize_url="https://login.tailscale.com/admin/settings/oauth",
+ token_url="https://api.tailscale.com/api/v2/oauth/token",
+ scopes=["audit:read"],
+ ),
+ )
+
+ def __init__(
+ self,
+ tailnet: str,
+ api_key: str = "",
+ client_id: str = "",
+ client_secret: str = "",
+ ):
+ self._tailnet = tailnet or "-"
+ self._api_key = api_key
+ self._client_id = client_id
+ self._client_secret = client_secret
+ # OAuth token cache
+ self._oauth_token: str | None = None
+ self._oauth_expires_at: float = 0.0
+
+ # ─────────────────────────── auth ────────────────────────────
+
+ async def _ensure_token(self) -> str:
+ """Return a valid bearer token, refreshing the OAuth token if needed."""
+ if self._api_key:
+ return self._api_key
+
+ if self._client_id and self._client_secret:
+ if self._oauth_token and time.time() < self._oauth_expires_at - 60:
+ return self._oauth_token # type: ignore[return-value]
+ # Fetch a new token via client-credentials grant.
+ async with httpx.AsyncClient(timeout=15.0) as client:
+ resp = await client.post(
+ "https://api.tailscale.com/api/v2/oauth/token",
+ data={
+ "grant_type": "client_credentials",
+ "client_id": self._client_id,
+ "client_secret": self._client_secret,
+ },
+ )
+ resp.raise_for_status()
+ payload = resp.json()
+ self._oauth_token = payload["access_token"]
+ self._oauth_expires_at = time.time() + int(payload.get("expires_in", 3600))
+ return self._oauth_token # type: ignore[return-value]
+
+ raise ValueError(
+ "TailscaleConnector: provide either 'api_key' or "
+ "both 'client_id' and 'client_secret'."
+ )
+
+ async def _auth_header(self) -> dict[str, str]:
+ token = await self._ensure_token()
+ return {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+
+ # ───────────────────────── contract ──────────────────────────
+
+ async def test_connection(self) -> dict[str, Any]:
+ try:
+ headers = await self._auth_header()
+ async with httpx.AsyncClient(timeout=15.0) as client:
+ # Probe: fetch the tailnet details. 200 ⟹ auth + scope OK.
+ resp = await client.get(
+ f"{_BASE}/tailnet/{self._tailnet}/acl",
+ headers=headers,
+ )
+ if resp.status_code == 200:
+ return {
+ "success": True,
+ "connector": self.connector_id,
+ "tailnet": self._tailnet,
+ }
+ return {
+ "success": False,
+ "connector": self.connector_id,
+ "error": f"HTTP {resp.status_code}: {resp.text[:300]}",
+ }
+ except Exception as exc:
+ return {"success": False, "connector": self.connector_id, "error": str(exc)}
+
+ async def fetch_alerts(self, since_seconds: int = 300) -> list[dict[str, Any]]:
+ start = datetime.now(UTC) - timedelta(seconds=since_seconds)
+ # Tailscale API accepts RFC-3339 timestamps as ``startTime`` / ``endTime``
+ start_iso = start.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+ events: list[dict[str, Any]] = []
+ headers = await self._auth_header()
+ cursor: str | None = None
+
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ while True:
+ params: dict[str, Any] = {"startTime": start_iso}
+ if cursor:
+ params["cursor"] = cursor
+
+ resp = await client.get(
+ f"{_BASE}/tailnet/{self._tailnet}/audit",
+ headers=headers,
+ params=params,
+ )
+
+ if resp.status_code == 403:
+ logger.warning(
+ "tailscale.audit_forbidden",
+ status=resp.status_code,
+ detail="Token is missing the audit:read scope.",
+ )
+ break
+
+ if resp.status_code != 200:
+ logger.warning(
+ "tailscale.audit_failed",
+ status=resp.status_code,
+ body=resp.text[:300],
+ )
+ break
+
+ payload = resp.json()
+ page: list[dict[str, Any]] = payload.get("auditLogs") or payload.get("logs") or []
+ events.extend(page)
+
+ # Tailscale uses cursor-based pagination.
+ cursor = payload.get("nextCursor") or payload.get("cursor")
+ if not cursor or not page:
+ break
+
+ return [self.normalize(e) for e in events]
+
+ # ───────────────────────── normalize ─────────────────────────
+
+ def normalize(self, raw: dict[str, Any]) -> dict[str, Any]:
+ action: str = raw.get("action") or raw.get("type") or ""
+ actor: str = (
+ raw.get("actor", {}).get("loginName")
+ or raw.get("actor", {}).get("id")
+ or raw.get("user")
+ or "unknown"
+ )
+
+ if action in _HIGH_SEVERITY_ACTIONS:
+ severity = "high"
+ elif action in _MEDIUM_SEVERITY_ACTIONS:
+ severity = "medium"
+ elif action.endswith(":delete") or action.endswith(":remove"):
+ # Catch-all for destructive operations not in the explicit sets.
+ severity = "medium"
+ else:
+ severity = "info"
+
+ # ``acl:update`` is especially important — diff the new vs old policy
+ # to surface what changed. Include in description if available.
+ description_parts = [f"action={action}", f"actor={actor}"]
+ target = raw.get("target") or raw.get("node") or {}
+ if isinstance(target, dict):
+ if target.get("name"):
+ description_parts.append(f"target={target['name']}")
+ if target.get("id"):
+ description_parts.append(f"target_id={target['id']}")
+ elif isinstance(target, str) and target:
+ description_parts.append(f"target={target}")
+
+ if action == "acl:update":
+ description_parts.append("(ACL policy modified — review diff for new access paths)")
+
+ # Normalise timestamp. Tailscale returns ISO-8601.
+ created_at: str | None = raw.get("created") or raw.get("timestamp") or raw.get("time")
+
+ return {
+ "source": self.connector_id,
+ "external_id": raw.get("id") or raw.get("eventId") or "",
+ "title": f"Tailscale: {action}" if action else "Tailscale audit event",
+ "description": "; ".join(description_parts),
+ "severity": severity,
+ "actor": actor,
+ "actor_email": raw.get("actor", {}).get("loginName") if isinstance(raw.get("actor"), dict) else None,
+ "src_ip": raw.get("actorIp") or raw.get("ip"),
+ "event_type": f"tailscale.{action}" if action else "tailscale.audit",
+ "raw_event": raw,
+ "created_at": created_at,
+ }