Connections

External Provider Ingestion

Push provider findings into BlackShield without giving BlackShield direct access to provider consoles or customer cloud accounts.

Provider agnostic

Use one endpoint for CSPM, CNAPP, endpoint, vulnerability, and SaaS security provider exports.

Customer controlled

Customers own the webhook, relay, or export job. BlackShield receives normalized findings by API key.

Freshness tracked

Each connector instance updates setup health after successful ingestion or repeated failures.

Configuration

  • Create an API key with ingest:external_findings.
  • POST provider-neutral findings to /api/v1/ingest/external-findings.
  • Use a stable provider and connector_instance for freshness, deduplication, and troubleshooting.
  • Preserve the original provider object in raw_payload for audit and future adapter upgrades.

Sample payload

{
  "provider": "generic",
  "connector_instance": "external-prod",
  "format": "blackshield_external_v1",
  "findings": [
    {
      "external_id": "provider-finding-001",
      "title": "Public storage bucket",
      "severity": "high",
      "status": "open",
      "finding_type": "misconfiguration",
      "resource": {
        "type": "storage_bucket",
        "id": "arn:aws:s3:::customer-data",
        "cloud_provider": "aws",
        "account_id": "123456789012",
        "region": "us-east-1"
      },
      "source_url": "https://provider.example/findings/001",
      "raw_payload": { "provider_object_id": "provider-finding-001" }
    }
  ]
}

SIEM & SOC Alert Stream Ingestion

In addition to scheduled provider finding exports, external SIEMs (Splunk, Datadog, Elastic, Microsoft Sentinel) can stream raw or correlated alerts directly into BlackShield via POST /api/v1/ingest/siem:

{
  "source": "splunk-es",
  "alerts": [
    {
      "rule_name": "Multiple Failed Logins Followed by Success",
      "severity": "high",
      "target_user": "admin@example.com",
      "source_ip": "198.51.100.42"
    }
  ]
}

Payloads are acknowledged with HTTP 202 Accepted and an IngestionJobAcceptedResponse envelope. Background workers normalize alerts into unified findings and correlate them against existing assets.

Success checks

  • The endpoint returns 202 with an ingestion job id.
  • The job completes with created or updated findings.
  • A queued job can be awaiting automatic recovery. BlackShield retries recoverable failures for up to 24 hours. Keep the original job id to follow its outcome.
  • Notification delivery retries independently: a delayed webhook does not undo saved findings. Failed jobs show a final error; BlackShield retains quarantine evidence for 90 days so operators can investigate.
  • The provider card in Connections shows recent freshness for the connector instance.
  • The finding source includes provider, connector instance, source URL, and raw payload provenance.
External Provider Ingestion