Connectors

Overview of available connectors and what evidence they collect.

Available Connectors

Connector	Controls	Status	Documentation
GitHub	CC6.1, CC6.6, CC7.2	✅ Available	Reference →
AWS	CC6.1, CC7.2	✅ Available	Reference →
Google Workspace	CC6.1, CC6.6	🚧 Coming soon	Reference →
Okta	CC6.1, CC6.6	🚧 Planned	-
Azure AD	CC6.1, CC6.6	🚧 Planned	-

GitHub Connector

Collects organization settings, repository configurations, and code review enforcement.

What It Collects

Organization Settings:

2FA enforcement status
Repository creation permissions
Member permissions and restrictions

Repository Configuration:

Branch protection rules
Required reviewers count
Required status checks
Admin enforcement settings

Code Review:

CODEOWNERS file presence
Code review requirement enforcement

Example Artifacts

Organization Settings (org_settings.json):

{
  "two_factor_requirement_enabled": true,
  "members_can_create_repositories": false,
  "members_can_create_public_repositories": false,
  "members_can_fork_private_repositories": false,
  "default_repository_permission": "read"
}

Branch Protection (repo_acme_backend_branch_protection.json):

{
  "required_pull_request_reviews": {
    "required_approving_review_count": 2,
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": true
  },
  "required_status_checks": {
    "strict": true,
    "checks": ["ci/tests", "ci/lint"]
  },
  "enforce_admins": {
    "enabled": true
  }
}

Configuration

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org
    repos:
      - your-org/backend
      - your-org/frontend
    branch: main

Required Scopes

repo:read or public_repo (for public repositories)
read:org

Creating a token:

GitHub → Settings → Developer Settings → Personal Access Tokens
Generate new token (classic)
Select scopes: public_repo + read:org
Copy token and set GITHUB_TOKEN environment variable

SOC 2 Controls

Control	Evidence Collected
CC6.1	2FA enforcement, repository permissions
CC6.6	CODEOWNERS enforcement, code review requirements
CC7.2	Branch protection, required reviews, status checks

Full GitHub Connector Reference →

AWS Connector

Collects IAM policies, CloudTrail configuration, and CloudWatch logs settings.

What It Collects

IAM Configuration:

Account password policy
Password complexity requirements
Password rotation requirements
MFA enforcement status

CloudTrail:

Trail configuration
Logging status (active/inactive)
Multi-region logging
Log file validation

CloudWatch Logs:

Log group configuration
Retention settings
Log streams

Example Artifacts

IAM Password Policy (iam_password_policy.json):

{
  "MinimumPasswordLength": 14,
  "RequireSymbols": true,
  "RequireNumbers": true,
  "RequireUppercaseCharacters": true,
  "RequireLowercaseCharacters": true,
  "AllowUsersToChangePassword": true,
  "ExpirePasswords": true,
  "MaxPasswordAge": 90,
  "PasswordReusePrevention": 12
}

CloudTrail Status (cloudtrail_trail_production_status.json):

{
  "IsLogging": true,
  "LatestDeliveryTime": "2026-01-09T12:34:56Z",
  "IsMultiRegionTrail": true,
  "LogFileValidationEnabled": true,
  "S3BucketName": "acme-cloudtrail-logs"
}

Configuration

sources:
  aws:
    mode: env
    region: us-east-1
    log_groups:
      - /aws/lambda/production-api
      - /aws/lambda/production-worker
    cloudtrail:
      trails:
        - production-trail

Required Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:GetAccountPasswordPolicy",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "logs:DescribeLogGroups"
      ],
      "Resource": "*"
    }
  ]
}

Setting up credentials:

# Option 1: Environment variables
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

# Option 2: AWS CLI profile
aws configure --profile evidence
# Then set: AWS_PROFILE=evidence

SOC 2 Controls

Control	Evidence Collected
CC6.1	Password policy, complexity requirements, MFA
CC7.2	CloudTrail logging, log retention, audit trails

Full AWS Connector Reference →

Google Workspace Connector

Collects user authentication settings, admin roles, and user lifecycle management.

What It Collects

2-Step Verification:

2SV enforcement status
User enrollment status
Enforcement date

Admin Roles:

Role assignments
Admin user list
Permission grants

User Lifecycle:

User provisioning
User suspension status
Account status changes

Example Artifacts

2SV Enforcement (users_2sv.json):

{
  "isEnforced": true,
  "enforcementDate": "2025-01-01",
  "usersEnrolled": 95,
  "totalUsers": 100,
  "enrollmentPercentage": 95.0
}

Admin Roles (role_assignments.json):

{
  "roles": [
    {
      "roleId": "admin",
      "roleName": "Super Admin",
      "assignees": [
        {
          "email": "admin@example.com",
          "assignedDate": "2025-01-01"
        }
      ]
    }
  ]
}

Configuration

sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@example.com

Required Scopes

https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

Setting up service account:

Go to Google Cloud Console
Create service account
Enable Admin SDK API
Delegate domain-wide authority
Download JSON key
Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

SOC 2 Controls

Control	Evidence Collected
CC6.1	2SV enforcement, MFA requirements
CC6.6	Admin role assignments, user lifecycle

Full Google Workspace Connector Reference →

Connector Comparison

By Control Coverage

CC6.1 (Logical Access Controls):

✅ GitHub (2FA enforcement)
✅ AWS (password policy)
✅ Google Workspace (2SV enforcement)

CC6.6 (Access Removal/Modification):

✅ GitHub (CODEOWNERS, code review)
✅ Google Workspace (admin roles, user lifecycle)

CC7.2 (Change Management):

✅ GitHub (branch protection, required reviews)
✅ AWS (CloudTrail logging)

By Setup Complexity

Connector	Setup Time	Complexity	Notes
GitHub	5 min	Easy	Just need personal access token
AWS	10 min	Medium	IAM policy + credentials
Google Workspace	20 min	Complex	Service account + domain delegation

By evidence Volume

Connector	Artifacts per Run	Typical Size
GitHub	3-10	5-20 KB
AWS	5-15	10-30 KB
Google Workspace	3-8	5-15 KB

Using Multiple Connectors

Combine connectors for comprehensive SOC 2 coverage:

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2

sources:
  # Code repository
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos: '*'

  # Infrastructure
  aws:
    mode: env
    region: us-east-1
    log_groups: '*'

  # Identity management
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@acme.com

Benefits:

Complete coverage - evidence from all critical systems
Cross-verification - Multiple sources prove same control
Comprehensive audit - Auditors see full security posture

Read-Only Guarantee

All connectors enforce read-only access:

Hardcoded Allowlists

// GitHub connector
const ALLOWED_SCOPES = [
  'repo:read',
  'public_repo',
  'read:org'
];

// AWS connector
const ALLOWED_ACTIONS = [
  'iam:GetAccountPasswordPolicy',
  'cloudtrail:DescribeTrails',
  'cloudtrail:GetTrailStatus',
  'logs:DescribeLogGroups'
];

// Google Workspace connector
const ALLOWED_SCOPES = [
  'admin.directory.user.readonly',
  'admin.directory.rolemanagement.readonly'
];

Runtime Validation

# If you accidentally use write scopes
evidence collect

✗ Configuration validation failed

Forbidden scope detected: repo (write access)

evidence SDK only uses read-only scopes.

Why this matters:

Security: SDK cannot modify your systems
Audit compliance: Auditors require proof of read-only access
Trust: You can verify source code to confirm read-only enforcement

Next Steps

Detailed Connector References See full API documentation for each connector.

SOC 2 Control Mappings Understand which controls each connector satisfies.

SOC 2 Controls →

Configuration Examples See complete configuration examples for each connector.

Configuration Guide →

Connectors

On this page