Operate and troubleshoot integrations

1. Runtime model

The scheduler discovers due integrations and queues jobs; it does not perform provider API calls. The persistent worker claims queued jobs and performs provider collection. Manual Run Sync and scheduled collection therefore converge on the same job queue.

2. Check runtime health

• Confirm the worker process/service is running in the expected hosted runtime.
• Confirm the scheduler/timer continues to run and its latest result has no errors.
• Review queued/running jobs for unexpected accumulation.
• Review recent provider runs for repeated errors or unexpected partial results.
• Review provider credential expiry and rotation ownership regularly.
• Confirm disabled Microsoft capabilities are not being queued by manual or scheduled execution.

3. Triage jobs and runs

1. Identify the integration ID, provider and capability.
2. Check whether the job is queued, running, successful or failed.
3. If queued for too long, check the worker and the job availability time.
4. If failed, use the friendly operator message first, then the protected server logs for the technical cause.
5. Inspect run metrics and sync state before resetting any watermark.

A partial run can still contain usable observations. Do not treat every partial result as equivalent to a failed connection.

4. Microsoft capability issues

A shared token failure affects the Microsoft connection, but capability readiness is independent after authentication. Entra user/role/Security Defaults failures are required Entra problems; MFA registration, Conditional Access and sign-in activity can remain limited. Microsoft 365 Security may succeed with partial stream coverage. Request not applicable to target tenant for Intune usually points to tenant provisioning/licensing, while Defender 403 / No active license found is a licence condition. Azure authentication with zero visible subscriptions should trigger a Reader/Security Reader RBAC check.

Disable capabilities that the tenant cannot currently use. PurpleWASP preserves the per-capability selection, and Run Sync/scheduled execution should queue only is_enabled=1 capabilities.

5. Google Workspace issues

• OAuth start returns to Integrations: ask a platform administrator to confirm that the centrally managed OAuth application is active and the registered redirect URI matches the environment.
• Error 400 redirect_uri_mismatch: compare the exact PurpleWASP redirect_uri with the Google Cloud OAuth Web client. Extensionless versus .php routing and trailing slash differences matter.
• Scopes expanded: reconnect Google Workspace so the administrator re-consents; do not assume an existing refresh token automatically gains new scopes.
• No worker dispatcher registered: ask a platform administrator to verify the integration service version and restart procedure; do not attempt host-level changes from an organisation account.
• No group observations: check google_workspace.identity.collection_status. groups_available=true with zero group rows is a valid empty result.
• Audit problems: inspect google_workspace.audit.collection_status and independent Admin/Login/OAuth Token sync state.
• No logging evidence: confirm CTRL-LOG-01 is adopted, applicable and active; Google collection does not auto-adopt Controls.

6. AWS capability issues

Start by separating shared authentication from individual AWS service readiness. STS identity/account verification proves the connection boundary; a later AccessDenied or unavailable service is a capability-specific condition.

• Account mismatch: verify the configured account ID, base credential, role ARN/trust policy and ExternalId where AssumeRole is used.
• Security Hub unavailable/not subscribed: treat the capability as unavailable for that account; other AWS capabilities can remain operational.
• Organizations expectations: the current baseline does not assume roles into member accounts. Organisation metadata/current-account context is not a multi-account scan.
• Zero Inspector findings: do not treat zero findings as proof of complete vulnerability coverage; review service/coverage facts.
• After PHP deployment: restart the persistent Integration Management worker so the long-running process loads the updated dispatcher/runtime.

GitHub event-driven collection

GitHub Auto-Refresh is independent of scheduled syncing. It can be enabled or disabled in Admin → Integrations → GitHub → Configuration without affecting manual collection.

• New event but no automatic job: check whether Auto-Refresh is turned off, whether the connection and relevant capability are enabled, and whether the GitHub event type is supported.
• Event received, collection limited: GitHub permissions, repository selection and plan features can limit code-security or audit streams. An unavailable stream must never be interpreted as no vulnerabilities.
• Multiple PurpleWASP organisations use one GitHub installation: the current integration requires an unambiguous active association. Contact your platform administrator; do not share credentials or modify another tenant's connection.
• Job succeeds but evidence does not appear: review whether the corresponding organisation Control is adopted, applicable and active. Individual automated checks may pass, fail or be inconclusive.
• Auto-Refresh off: accepted events can remain in delivery history without creating background jobs; previously stored events are not replayed when you turn it on.

For account-level installation changes, consult GitHub's installed App guidance. Contact authorised PurpleWASP support for platform logs and routing investigations; do not attach raw webhook bodies or credentials.

8. Qualys issues

If Test Connection fails, verify the Qualys platform/base URL, API credentials, provider API access and TLS/CA configuration. If a run succeeds but Asset findings do not change, inspect the Asset-domain ingestion/matching step rather than moving provider credentials or scheduling logic back into Asset Management.

9. Control evidence automation

If provider collection succeeds but no automated Control evidence appears, confirm the Control is already adopted, applicable and active; the canonical rule is active and mapped; and the run contains the observation types the rule requires. A repeated evaluation of the same run/rule is intentionally idempotent. AWS includes narrow automated tests for root MFA, root access-key absence, Config recording, CloudTrail logging and GuardDuty enablement; Google Workspace includes active/privileged MFA enrollment and Audit logging-availability tests; a failed test is assurance evidence for that test, not a reason to rewrite the whole Control status.

10. Rotate credentials safely

1. Create the replacement provider secret/password.
2. Update PurpleWASP without exposing the secret in logs or support channels.
3. Run Test Connection.
4. Run one manual sync and confirm a successful or expected partial result.
5. Revoke the old provider credential only after the replacement is proven where overlap is supported.

For Google Workspace, credential recovery normally means reconnecting the OAuth grant and completing administrator consent again; never move refresh tokens into support channels.

11. Canonical integration runtime

The persistent worker and periodic scheduler must use the canonical Integration Management runtime, including integration_worker.php and integration_scheduler.php. Host-level service management and absolute paths are deployment-specific.

Legacy Asset Management integration-worker/scheduler paths are retired and should not be restored.

Related implementation guidance

Read the first-time integration setup instructions or download the customer-facing first-time handbook. Advanced deployment and incident response runbooks are available only through authorised support channels.

Related guidance