> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Pull vendor audit logs into Squasher with a connector: plan, connect, verify, and disconnect from the API or the CLI.

A connector pulls audit logs from a vendor API, for example the Okta System Log or the GitHub
organization audit log. Squasher polls the vendor on a schedule, keeps a cursor so that it reads
each event once, and stores each event as a log record. Every connector is set up in the same four
steps.

1. **Plan.** See the params, the secrets, the scopes to grant, the exact endpoints that Squasher
   calls, and the request cost per hour. A plan changes nothing.
2. **Connect.** Send the params and the secrets. Squasher pulls one page to verify them before it
   stores anything. When the page is good, Squasher stores the secrets encrypted and starts to poll.
3. **Verify.** Pull one page again at any time with the stored secrets. Verify shows sample records,
   the same records mapped to OCSF, and the OCSF coverage per class. It sends nothing to your
   project.
4. **Disconnect.** Stop polling and delete the stored secrets. This cannot be undone. To start
   again, connect again.

## Connector catalog

| Connector | Vendor | Auth | Setup from the API |
| - | - | - | - |
| `okta.system_log` | Okta | OAuth client credentials (JWT) | Yes |
| `github.audit_log` | GitHub | Organization owner token | Yes |
| `aws.cloudtrail_s3` | Amazon Web Services | IAM role with ExternalId | Connect and verify only |
| `aws.cloudtrail_sqs` | Amazon Web Services | IAM role with ExternalId | Connect and verify only |

For the AWS connectors, scheduled pulls are not available yet. Connect and verify work now.

`squasher connectors list` shows the current catalog. `squasher connectors get <id>` shows what a
connector needs.

## Set up a connector with the CLI

```bash theme={null}
squasher connections plan --project "$SQUASHER_PROJECT_ID" github.audit_log \
  --param github_org=acme

squasher connections create --project "$SQUASHER_PROJECT_ID" github.audit_log \
  --param github_org=acme --secrets-file secrets.json

squasher connections verify --project "$SQUASHER_PROJECT_ID" <connection_id>
squasher connections delete --project "$SQUASHER_PROJECT_ID" <connection_id> --dry-run
```

`secrets.json` is a JSON object of secret values by name, for example
`{"access_token": "..."}`. Use `--secrets-file -` to read it from stdin. The CLI does not take a
secret as a flag value, so the secret does not go into your shell history.

## Connect an AWS account

AWS connectors read with an IAM role in your account. Squasher assumes the role with an
ExternalId that Squasher issues for your project and connector. You cannot choose the ExternalId,
so another Squasher customer cannot use your role.

1. Run `connections.plan` with the connector params. The plan shows `aws_role.external_id`, the
   principal to trust in `aws_role.trust_principal` (`arn:aws:iam::381347172594:root`, the
   Squasher AWS account), and the trust policy condition, for example
   `{"StringEquals": {"sts:ExternalId": "sq-..."}}`.

2. Create the reader role. In its trust policy, allow `sts:AssumeRole` for the principal with the
   condition, and grant the actions in the plan `scopes`:

   ```json theme={null}
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "AWS": "arn:aws:iam::381347172594:root" },
         "Action": "sts:AssumeRole",
         "Condition": { "StringEquals": { "sts:ExternalId": "sq-..." } }
       }
     ]
   }
   ```

3. Connect with the role ARN in the `role_arn` param. `secrets` is an empty object.

```bash theme={null}
squasher connections plan --project "$SQUASHER_PROJECT_ID" aws.cloudtrail_sqs   --param aws_region=us-east-1 --param aws_account_id=123456789012   --param trail_bucket=acme-cloudtrail-logs   --param notification_queue_url=https://sqs.us-east-1.amazonaws.com/123456789012/acme-trail   --param role_arn=arn:aws:iam::123456789012:role/squasher-reader
```

Verify of `aws.cloudtrail_sqs` reads one batch of S3 notifications. It does not delete a message:
each message is visible again at once, so the next pull reads it.

## Safe retries

* `connections.create` and `connections.delete` take `dry_run=true`. A dry run returns the
  preview and changes nothing.
* Send an `Idempotency-Key` header to retry safely. A retry with the same key and the same request
  in 24 hours gets the first response. The same key with a different request gets `422`.
* `connections.delete` needs an `Idempotency-Key`. The CLI sends a new one for each delete.

## Access

Listing connectors and connections needs `providers:read`. Plan, connect, verify, and disconnect
need `providers:write`. The API never returns a stored secret.

See the [Connectors API](https://docs.squasher.ai/api-reference/connectors.md) for every operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.