Connecting your sources¶
A source is a place detections come from — a cloud provider, a SaaS control plane, an endpoint tool, or a network sensor. This page explains how SheerSight connects to each one, then gives per-source steps for the credential you create and paste in.
The golden rule throughout: you only ever create a read-only credential, and it is encrypted in your browser before it leaves your screen. SheerSight relays ciphertext only — nobody in the middle, including us, can read it. See Security for the full trust model.
How connecting works¶
Every source follows the same shape:
1. In the vendor (GitHub, AWS, Cloudflare, …)
create a READ-ONLY credential — one scope, no write access.
│
2. Paste it into the SheerSight console (Integrate → Sources).
It is encrypted IN YOUR BROWSER to your VM's key.
│ (only ciphertext is relayed — we never see the secret)
▼
3. Your dedicated VM's agent decrypts it locally and starts
collecting — OUTBOUND ONLY. No inbound ports on the vendor
or on your VM.
│
▼
4. Detections begin appearing in the console.
In the console, open Integrate → Sources, click the source you want, fill
in its fields, and press Encrypt & connect. You'll see
"Encrypted in your browser and relayed. Your VM will apply it shortly." — the
credential is wrapped to your VM's age public key client-side, and only the
resulting ciphertext is sent.
Why it's safe to paste a token here
The console holds no long-lived secrets. The value you type is encrypted in the browser tab before any network request, delivered to your VM as ciphertext, and decrypted only there. The relayed credentials panel shows each one as pending → applied once your VM picks it up.
Before you start¶
- Your VM is enrolled. The Sources panel needs your VM's
agerecipient (public key). If it says "Your VM is not enrolled yet", finish onboarding a host first. - Console access. You can sign in and reach Integrate → Sources.
- Admin on the vendor. Creating a read-only token/role usually requires an org owner or account admin on that vendor. That's the only thing you need from them — one read-only grant, no standing access for us.
Least privilege, always
Every credential below is read-only and scoped to just the audit or findings data SheerSight monitors. None of them can change, delete, or take action on anything in your environment.
Source reference¶
Each source shows what SheerSight reads, where to create the credential, the read-only scope to grant, and what you paste into the console.
Identity & SaaS audit logs¶
Google Workspace¶
| What SheerSight reads | Admin, login, and token activity from the Admin SDK Reports API. |
| Where to create it | Google Cloud → a service account with domain-wide delegation, plus an admin account to impersonate. |
| Read-only scope | https://www.googleapis.com/auth/admin.reports.audit.readonly (authorize the service account's client ID for exactly this scope in Google Admin → Security → API controls → Domain-wide delegation). No broader scope is needed. |
| What you paste | The service account JSON key, the delegated admin email, and your Customer ID (or leave the default my_customer). |
Note
Domain-wide delegation can take a few minutes to propagate after you authorize it — a handful of early auth retries right afterward are normal.
GitHub¶
| What SheerSight reads | Your organization's audit log (repos made public, 2FA changes, new PATs/runners, branch-protection and secret tampering, unusual actor volume). |
| Where to create it | GitHub → org Settings → a fine-grained personal access token (or a classic token), created by an org owner. |
| Read-only scope | read:audit_log only. No write access, no repository-contents access. |
| What you paste | Your organization slug and the personal access token. |
GitLab¶
| What SheerSight reads | A group's audit events (project made public, group 2FA disabled, new deploy keys/tokens/runners, protected-branch or CI-variable tampering, unusual actor volume). |
| Where to create it | GitLab → the group → Access tokens (or a personal token scoped to the group), created by a group owner. |
| Read-only scope | A group-scoped token with audit-log read (read_api / read_audit). Scoped to the one group SheerSight monitors. |
| What you paste | The Group ID and the access token. |
Cloudflare¶
| What SheerSight reads | Account audit logs (API tokens created, member/2FA-enforcement changes, firewall-rule deletions, Logpush/DNS tampering, actor bursts). |
| Where to create it | Cloudflare dashboard → My Profile / Account → API Tokens → create token. |
| Read-only scope | Account → Audit Logs → Read only. |
| What you paste | Your Account ID and the API token. |
Note
If your account is on Cloudflare's newer audit-logs API rather than the legacy endpoint, let us know before you connect so we can point the collector at the right one.
Cloud platforms¶
AWS¶
| What SheerSight reads | CloudTrail, plus GuardDuty / Inspector / Security Hub / WAF findings, delivered to your log bucket. |
| Where to create it | AWS IAM → a read-only collector identity for your CloudTrail/findings S3 bucket. |
| Read-only scope | s3:GetObject / s3:ListBucket on the log bucket only. Preferred: an assume-role with a trust policy + external ID (we provide the exact IAM policy JSON for your team to review and apply). |
| What you paste | An Access key ID and secret access key for the read-only collector user. |
Tip
You (or your IaC) wire your existing CloudTrail/GuardDuty bucket to notify the collector. This repo never creates or modifies your log bucket, and the role grants read-only access to that one bucket.
Azure¶
| What SheerSight reads | Microsoft Defender for Cloud alerts and Azure Activity Log (control-plane changes). |
| Where to create it | Entra ID → App registrations → New registration, add a client secret. |
| Read-only scope | Assign the app's service principal Reader — or, more tightly, Security Reader — on the subscription. Both are read-only. |
| What you paste | Tenant ID, Client ID, Client secret, and Subscription ID. |
GCP¶
| What SheerSight reads | Cloud Audit Logs (admin activity + data access) and Security Command Center findings. |
| Where to create it | GCP → IAM & Admin → Service Accounts → create a service account and a JSON key. |
| Read-only scope | roles/logging.viewer on the project and roles/securitycenter.findingsViewer on the organization. Both read-only. |
| What you paste | Project ID, Organization ID, the service account email, and the service account key JSON. |
Endpoint detection & response (XDR)¶
These sources are themselves detection engines — SheerSight ingests their findings and triages which ones deserve an immediate page.
CrowdStrike¶
| What SheerSight reads | Falcon alerts (severity-scored, with MITRE ATT&CK tactic/technique). |
| Where to create it | Falcon console → Support → API Clients & Keys → create an OAuth2 API client. |
| Read-only scope | Alert/detection Read only. It cannot resolve alerts, trigger response, or change policy. |
| What you paste | The API client ID and API client secret. |
SentinelOne¶
| What SheerSight reads | Threats from the Management Console (confidence-scored, classified, with mitigation history). |
| Where to create it | SentinelOne console → a service user / API token with Threats-read visibility. |
| Read-only scope | Threats Read only. It cannot mitigate/resolve threats or change policy. |
| What you paste | The API token. |
Device management (MDM)¶
Kandji¶
| What SheerSight reads | Device posture events (compliance, on-device threats, enrollment/management-state changes). |
| Where to create it | Kandji → Settings → Access → API Token. |
| Read-only scope | A token with device/posture read visibility. It cannot push MDM commands, change policy, or wipe a device. |
| What you paste | The API token. |
JumpCloud¶
| What SheerSight reads | System Insights posture and Directory Insights events. |
| Where to create it | JumpCloud admin console → your account → API key. |
| Read-only scope | System Insights read + Directory Insights read only. It cannot modify directory objects or push commands. |
| What you paste | The API key. |
Network & host sensors¶
These two don't use a vendor token — they run on infrastructure you control.
Suricata IDS¶
| What SheerSight reads | Network intrusion-detection alerts from a Suricata sensor. |
| How it connects | No API credential. The Suricata network sensor runs on your dedicated VM. |
| What to do | Nothing to paste — just contact us to tune which interfaces/traffic it monitors. |
Wazuh¶
| What SheerSight reads | Host and file-integrity monitoring, brute-force, and privilege-escalation alerts from enrolled Wazuh agents. |
| Where to create it | Your Wazuh manager → the agent registration password. |
| What you paste | The agent registration password. |
| Also required | Install the Wazuh agent on each host you want monitored and enroll it against the manager. |
Verifying a connection¶
After you press Encrypt & connect:
- The relayed credentials panel shows the entry as pending, then applied once your VM decrypts and loads it (usually within a minute or two).
- The source's status badge in the Sources list moves from not connected → up once data is flowing.
- Detections/telemetry for that source begin appearing in the console.
First real backfill
On the first live poll for audit sources (GitHub, Google Workspace, Cloudflare), it's worth spot-checking the event count and time range against the vendor's own audit-log view for the same window, to confirm everything lines up before you rely on steady-state output.
Troubleshooting¶
- Stuck on pending. Confirm your VM is online in the fleet view and has outbound internet access — the agent has to dial out to fetch the ciphertext and to poll the vendor.
- Badge stays not connected. Re-check the credential's scope on the vendor side (it must include the read permission listed above) and that any IDs (org/account/group/subscription/project) are correct.
- Authorized but no data (Google Workspace). Give domain-wide delegation a few minutes to propagate before troubleshooting further.
- Something else. See the FAQ, or email security@sheersafe.com for anything security-related.