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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.mdnew file mode 100644index 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.tsindex 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.jsonindex 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.yamlnew file mode 100644index 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.jsonindex 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.yamlnew file mode 100644index 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: truediff --git a/services/connectors/app/connectors/__init__.py b/services/connectors/app/connectors/__init__.pyindex 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 M365AuditConnectorfrom app.connectors.microsoft_sentinel import MicrosoftSentinelConnectorfrom app.connectors.okta import OktaConnectorfrom app.connectors.splunk import SplunkConnector+from app.connectors.tailscale import TailscaleConnectorif 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.pynew file mode 100644index 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,+ }