Connect GitHub, Google Workspace and other integrations

1. Understand the Integration Management model

Provider configuration is managed centrally from Admin → Integrations. PurpleWASP stores provider connections, encrypted credentials, enabled capabilities, jobs, runs, sync state and normalized observations in the tenant Integration Management service. Asset Management and Control Management consume the results according to their own responsibilities.

Manual evidence remains supported. Integrations are an optional collection path, not a prerequisite for using PurpleWASP. Where a Control has been adopted and the associated rule is applicable, collected facts can support automated assessments; they do not automatically mark an entire Control implemented.

2. Configure Microsoft

PurpleWASP uses one shared Microsoft tenant connection with independently enabled capabilities: microsoft.entra_identity, microsoft.m365_security, microsoft.intune_devices, microsoft.defender_endpoint and microsoft.azure_resources. Register or select a Microsoft Entra application for server-to-server collection, grant the permissions needed by the capabilities you intend to use, then enter the tenant ID, client ID and client secret in PurpleWASP.

• Entra ID: User.Read.All, RoleManagement.Read.Directory, Policy.Read.All and AuditLog.Read.All for the supported identity streams.
• Microsoft 365 Security: SecurityEvents.Read.All, SecurityIncident.Read.All and SecurityAlert.Read.All for the supported security streams.
• Intune: DeviceManagementManagedDevices.Read.All and DeviceManagementConfiguration.Read.All, plus an active Intune service/licence.
• Defender for Endpoint: Machine.Read.All and Vulnerability.Read.All, plus an active Defender for Endpoint licence.
• Azure: Azure subscription RBAC such as Reader for inventory and Security Reader where Defender for Cloud posture is required.

Select Test Connection before activation. PurpleWASP reports readiness per capability. A licence-dependent Intune or Defender failure does not invalidate usable Entra ID, Microsoft 365 Security or Azure capabilities. After saving, enable only the capabilities the organisation actually uses; disabled capabilities are not queued by Run Sync or the scheduler.

3. Configure AWS

PurpleWASP uses one AWS account connection with eight independently enabled capabilities: aws.account_inventory, aws.iam_security, aws.resource_inventory, aws.cloudtrail_audit, aws.config_compliance, aws.security_hub, aws.guardduty and aws.inspector.

1. Open Admin → Integrations and select Amazon Web Services.
2. Choose the credential pattern. Prefer AssumeRole + ExternalId for customer environments where possible; stored access-key credentials remain supported where required.
3. Enter the expected AWS account ID and connection configuration. PurpleWASP resolves credentials at runtime and verifies identity/account alignment with STS.
4. Run Test Connection. Authentication is shared, but readiness is reported independently for all eight capabilities. A capability can be limited by permissions or unavailable because the underlying AWS service is not subscribed/enabled without invalidating the whole connection.
5. Activate the connection, enable only the required capabilities and run one manual sync.

4. Configure Google Workspace

PurpleWASP uses one Google Workspace OAuth connection with two independently enabled capabilities: google_workspace.identity and google_workspace.audit. The OAuth application Client ID/Secret are managed centrally in Platform Management; the organisation connection stores its encrypted refresh token.

1. Ensure the Google Workspace OAuth application is active in Platform Management.
2. Register the exact PurpleWASP production callback URI in the Google Cloud OAuth Web client. The current production callback is https://purplewasp.com/integration_management/google_workspace_oauth_callback.
3. Open Admin → Integrations, select Google Workspace and choose Connect Google Workspace.
4. Complete Google administrator consent. Identity uses Directory user/group/role-management read access; Audit uses Admin Reports audit read access.
5. Run Test Connection. A healthy result reports Identity users/groups/roles and Audit Admin/Login/OAuth Token probes successfully.
6. Activate the connection, enable the required capabilities and run one manual integration cycle.

If the connection does not complete, contact your PurpleWASP administrator. Do not share OAuth authorisation codes or refresh tokens in support messages.

5. Connect GitHub and enable optional Auto-Refresh

PurpleWASP uses one GitHub App installation to collect supported organisation security, repository configuration, code-security and audit information. Your organisation decides which repositories the App can access. Depending on your GitHub plan and permission grants, some streams can be limited or unavailable; an unavailable result does not mean there are zero findings.

1. Ask a GitHub organisation owner to install the PurpleWASP GitHub App. Review the permissions it requests and choose Only select repositories when full-repository access is not required. Do not provide a personal access token or a private PEM key.
2. In GitHub, open Organisation Settings → GitHub Apps, locate the installed App and select Configure. Record the exact organisation login and the installation ID from the installation details (the installation ID is different from the platform App ID). If the ID is not visible, ask the PurpleWASP platform team for an approved way to obtain it.
3. In PurpleWASP open Admin → Integrations → GitHub → Configuration. Enter a meaningful connection name, the exact GitHub organisation login and the numeric installation ID. Use Test connection, then save and activate the connection.
4. Enable the required capabilities under Integration capabilities. Use Run Integration once to verify a baseline collection. A Control assessment is only created when its matching Control is adopted, active and applicable.
5. To refresh after supported GitHub changes, turn on Automatically refresh evidence on GitHub changes. The setting is off by default and is separate from scheduled syncing. A fresh supported event can queue a background collection; no browser session is required for the ongoing webhook.
6. Open Run history to check the resulting background job and collection. In Control Management, review the matching test outcome and evidence history. Passing a narrow test is not proof that every related security requirement has been met.

GitHub's own guides explain installing a GitHub App and reviewing an installed App's access.

6. Configure Qualys

1. Open Admin → Integrations and select Qualys.
2. Enter the Qualys base/platform URL and API credentials for the organisation.
3. Run Test Connection and resolve authentication, API-access or TLS problems before activation.
4. Activate the connection and enable the vulnerability-finding capability.

The connection and runtime are owned by Integration Management. Vulnerability findings, Asset matching and technical-exposure lifecycle remain Asset Management domain data.

7. Activate and run the first collection

1. Save and activate the connection after the test succeeds.
2. Enable only the capabilities the organisation intends to run.
3. Run a manual sync so you can validate the provider before relying on the schedule.
4. Confirm the job moves from queued/running to success or an expected partial state.
5. Allow at least one scheduled cycle and confirm the scheduler queues due work and the worker processes it.

Manual and scheduled runs use the same Integration Management job queue. The web request queues work; the background worker performs the provider API collection.

8. Understand where collected data goes

Microsoft: enabled capabilities emit normalized observations for their own domains and can feed Asset or Control consumers according to the capability.

AWS: normalized account/IAM/security/resource facts feed the same provider-neutral model. Resource inventory can materialise Asset integration records. Inspector findings materialise vulnerability findings only when a provider resource is matched to a PurpleWASP Asset. Control automation currently includes narrow AWS tests for root MFA, root access-key absence, AWS Config recording, CloudTrail logging and GuardDuty enablement.

Google Workspace: Identity emits user/role/group/MFA/collection facts; Audit emits Admin/Login/OAuth Token events, summaries, signals and collection status. Automated MFA evidence supports adopted CTRL-IAM-03, while logging-availability evidence supports adopted CTRL-LOG-01 without changing the Control implementation status.

Qualys: the shared integration runtime collects provider data and the vulnerability domain consumes it in Asset Management.

9. Verify the implementation

• Microsoft Test Connection reports readiness independently for Entra ID, Microsoft 365 Security, Intune, Defender for Endpoint and Azure.
• AWS Test Connection verifies the configured account with STS and reports readiness independently for all eight AWS capabilities.
• Google Workspace OAuth completes through the registered callback and Test Connection reports Identity and Audit probes successfully.
• Google Workspace Identity/Audit manual execution completes through the canonical worker, including audit stream watermarks and applicable Control evidence.
• Qualys Test Connection passes.
• A manual job is processed by the canonical Integration Management worker.
• The scheduler completes without errors and queues only due work.
• Only enabled capabilities create jobs.
• AWS resource observations/Asset hand-off and any applicable automated Control evidence are visible after collection.
• Automated Control evidence is created only for adopted/applicable Controls and does not overwrite implementation status.

9. Know the current scope

The Microsoft multi-capability architecture is implemented and deployed. microsoft.entra_identity, microsoft.m365_security and microsoft.azure_resources have passed acceptance; microsoft.intune_devices and microsoft.defender_endpoint remain pending licensed-tenant acceptance testing.

AWS is implemented end-to-end with eight capabilities, STS identity verification, independent capability readiness, Asset hand-off and Control evidence automation. The acceptance account reported seven capabilities available and Security Hub unavailable because the account was not subscribed. Cross-account member scanning is not yet implemented.

Google Workspace is complete and production-accepted for google_workspace.identity and google_workspace.audit, including OAuth, normalized observations, independent audit watermarks and automated evidence for MFA and audit logging availability.

Qualys vulnerability collection is complete under qualys.vulnerability_findings.

First-time integration handbook

For a printable introduction covering setup, supported capabilities, choosing Auto-Refresh and reviewing evidence, download the customer-facing first-time guide.

First-Time Integration Handbook

Platform deployment, database recovery and security-engineering runbooks are restricted to authorised operators and are not distributed from the public Help Centre.

Related guidance