Skip to content

Common Integration Troubleshooting

This guide covers issues common to all Signal Client pull-based integrations. For vendor-specific troubleshooting, see the individual integration guides.

Connection Issues

Cannot Reach Vendor API

Conductor must have outbound HTTPS (port 443) access to the vendor's API endpoints. Verify connectivity from the Conductor host:

# Test basic connectivity
curl -I https://<vendor-api-endpoint>

# If behind a forward proxy
export HTTPS_PROXY=http://proxy:port
curl -I https://<vendor-api-endpoint>

If your environment uses a forward proxy, configure it in the Conductor node settings via wfa configure.

TLS Certificate Errors

If the vendor API endpoint uses a certificate signed by a private CA:

  1. Copy the CA certificate to /witfoo/certs/
  2. Run sudo wfa configure and update the CA certificate path

  3. Restart Signal Client:

    docker restart signal-client-svc

DNS Resolution Failures

If Signal Client logs show DNS errors:

  1. Verify the Conductor host can resolve the vendor hostname:

    nslookup <vendor-api-endpoint>

  2. Check /etc/resolv.conf for correct upstream DNS servers

  3. If using internal DNS, ensure the vendor domain is not blocked

Authentication Issues

Token Expired

Most API tokens have expiration dates. If a previously working integration stops collecting data:

  1. Check Signal Client logs for 401 errors:

    docker logs signal-client-svc --tail=100 | grep "401"

  2. Generate a new token in the vendor console

  3. Update the credentials in the Conductor UI → Integrations
  4. Click Save — new credentials take effect within seconds via NATS KV watch

OAuth2 Token Refresh Failures

For OAuth2 integrations (Microsoft, CrowdStrike, Sophos, Wiz, etc.):

  • Verify the Client ID and Client Secret are correct
  • Check that the application/service principal has not been deleted
  • Confirm required API scopes/permissions are still granted
  • Some vendors require admin consent to be re-granted after scope changes

IP Allowlist

Some vendors restrict API access by source IP address:

  1. Determine the Conductor host's public IP
  2. Add it to the vendor's API allowlist (often in Settings → API → IP Restrictions)
  3. If Conductor uses a NAT gateway, add the NAT IP instead

Rate Limiting

HTTP 429 Too Many Requests

Signal Client implements automatic exponential backoff on 429 responses. If you see persistent rate limiting:

  1. Increase the polling interval — reduces the frequency of API calls
  2. Reduce concurrent integrations — if many integrations poll the same vendor simultaneously

  3. Check vendor rate limits — each vendor has different quotas:

    Vendor Typical Rate Limit
    CrowdStrike 100 req/min
    Microsoft Graph 10,000 req/10min
    Okta 600 req/min
    Tenable 300-500 req/min
    SentinelOne 1000 req/min
    Qualys 300 req/hr

  4. Contact the vendor to request a rate limit increase if needed

Data Issues

No Artifacts Appearing

  1. Verify the integration is Enabled in the Conductor UI

  2. Check for errors in Signal Client logs:

    docker logs signal-client-svc --tail=100

  3. Verify data exists in the vendor console for the polling time window

  4. Check the NATS JetStream stream:

    docker exec broker-edge-svc nats stream info DATA

  5. Confirm Artifact Exporter is running and connected to Analytics:

    docker logs artifact-exporter-svc --tail=50

Duplicate Artifacts

WitFoo's ProtoGraph deduplication in the Artifact Filter service automatically reduces duplicate events. If you see excessive duplicates:

  1. Reduce the polling interval to avoid overlapping time windows
  2. Check if multiple integration instances are configured for the same vendor account
  3. Verify checkpoint tracking is working (Signal Client resumes from the last successful position)

Missing Events

If some events appear but others are missing:

  1. Check the vendor's data retention settings — some APIs only return recent data
  2. Verify the API credentials have permissions for all required data types
  3. Some integrations collect multiple data types on different schedules (e.g., alerts every 5min, assets every 1hr)

Performance

High Memory Usage

If Signal Client shows elevated memory usage:

  • Reduce the number of concurrent polling integrations
  • Increase polling intervals for less critical sources
  • Check for vendors that return large batch responses (thousands of records per page)

Slow Polling

Common causes of slow poll cycles:

  • Network latency to the vendor API endpoint
  • Large data volumes — consider narrower time windows or more frequent polling to keep batch sizes small
  • Vendor API rate limiting — 429 responses trigger backoff delays
  • DNS resolution delays — verify DNS is fast from the Conductor host

Diagnostic Commands

Quick reference for troubleshooting from the Conductor host:

# Signal Client logs (last 100 lines)
docker logs signal-client-svc --tail=100

# Signal Client logs filtered by integration
docker logs signal-client-svc --tail=200 | grep "<connector-name>"

# Check container health
docker inspect --format='{{.State.Health.Status}}' signal-client-svc

# NATS stream statistics
docker exec broker-edge-svc nats stream info DATA

# Test outbound connectivity to a vendor
curl -sI -o /dev/null -w "%{http_code}" https://<vendor-api-endpoint>

# Check container resource usage
docker stats signal-client-svc --no-stream

See also: Integration Catalog · Signal Client · General Conductor Troubleshooting