BLACKSHIELD

دليل عام

Deploy BlackShield Defense-in-Depth Appliances

Choose and run the BlackShield enforcement appliance that matches your control gap: TCP edge, internal segmentation, host runtime, HTTP/WAF, query guardrails, or identity/session gates. الجمهور: Founders, platform engineers, and security engineers who need clear deployment choices and working appliance examples. وقت الإعداد المعتاد: 10-20 minutes.

reference

Use this if

Choose and run the BlackShield enforcement appliance that matches your control gap: TCP edge, internal segmentation, host runtime, HTTP/WAF, query guardrails, or identity/session gates.

Audience
Founders, platform engineers, and security engineers who need clear deployment choices and working appliance examples
Typical time
10-20 minutes

قبل البدء

  • Create a scoped BlackShield API key for appliance ingestion and connector health reporting.
  • Choose one appliance for the first proof point. Do not deploy all six unless each one has a real traffic path to protect.
  • Confirm Docker can reach the BlackShield API over outbound HTTPS and that local metrics port 9090 is available.
  • Set the upstream target before putting perimeter or application appliances in a traffic path.

Placement diagrams

Use these views to match an appliance to a real traffic path before you put it in line.

Placement overview

Place only the appliance that matches the boundary you actually control; each appliance polls BlackShield and reports findings independently.

flowchart LR
  Internet["Internet and external clients"]
  Edge["Perimeter TCP Edge Appliance"]
  Internal["Internal network segments"]
  Hosts["Linux hosts"]
  App["Application and API tier"]
  Data["Data and SQL-like access path"]
  Admin["Admin and identity-sensitive paths"]
  Control["BlackShield control plane"]

  Internet --> Edge
  Edge --> App
  Internal --> App
  Internal --> Hosts
  App --> Data
  Admin --> App

  Edge -. "threat intel sync and findings" .-> Control
  Internal -. "segmentation policy and findings" .-> Control
  Hosts -. "runtime indicators and findings" .-> Control
  App -. "WAF signatures and findings" .-> Control
  Data -. "data policy and findings" .-> Control
  Admin -. "identity policy and findings" .-> Control

The perimeter appliance is a TCP edge proxy, while the application appliance is the HTTP/WAF control.

Inline traffic-path examples

Use inline appliances where traffic already has a listener, proxy, or query path that can be routed through the container.

flowchart TB
  Client["Client"]
  TcpProxy["Perimeter TCP proxy"]
  TcpService["Public TCP service"]

  Browser["Browser or API client"]
  Waf["Application WAF reverse proxy"]
  Api["HTTP app or API"]

  Worker["Service issuing query"]
  SqlProxy["Data SQL proxy"]
  Database["Database-facing service"]

  Operator["Admin user or service"]
  IamGate["Security IAM gate"]
  AdminApi["Admin API"]

  Client --> TcpProxy --> TcpService
  Browser --> Waf --> Api
  Worker --> SqlProxy --> Database
  Operator --> IamGate --> AdminApi

Endpoint runtime monitoring is host-local rather than an inline traffic proxy; run it only where host process visibility is allowed.

Configuration enables capabilities

The container starts with a common BlackShield connection, then specific env vars determine which enforcement behavior is active. UPSTREAM_ADDR enables TCP forwarding, UPSTREAM_URL enables WAF proxying, and METRICS_ADDR enables local Prometheus metrics.

flowchart LR
  Base["BLACKSHIELD_API_URL and BLACKSHIELD_API_KEY"]
  Metrics["METRICS_ADDR"]
  Listen["LISTEN_ADDR"]
  Tcp["UPSTREAM_ADDR"]
  Http["UPSTREAM_URL"]
  FailClosed["FAIL_CLOSED=true"]
  Endpoint["ENFORCEMENT_MODE=enforce"]
  Body["MAX_BODY_BYTES"]

  Base --> Sync["Sync policy or threat intelligence"]
  Base --> Findings["Report findings and health"]
  Metrics --> Prometheus["Expose local Prometheus metrics"]
  Listen --> Listener["Open appliance listener"]
  Tcp --> TcpForward["Enable perimeter TCP forwarding"]
  Http --> ReverseProxy["Enable application WAF reverse proxy"]
  FailClosed --> Blocking["Block when sync health is unavailable"]
  Endpoint --> ActiveResponse["Enable endpoint active response"]
  Body --> BodyLimit["Enforce request body inspection limit"]

Leave fail-closed and endpoint enforcement in audit-friendly settings until sync health and telemetry are proven.

Guide walkthrough

الخطوة 1

Choose the appliance that matches the control gap

Start with the boundary where a missing active control would hurt first. Perimeter protects TCP entry points; Application is the WAF.

  • Layer 1 - Perimeter Boundary: Perimeter TCP Edge Appliance. Use when: Use it when the control gap is known bad source IPs reaching public TCP listeners before application code runs. Protects: Public TCP services and edge entry points from known hostile IPs and CIDRs. Placement: At the network edge as a TCP proxy. This is not a WAF; use the Application WAF for HTTP request inspection.
  • Layer 2 - Network Security: Network Segmentation Appliance. Use when: Use it when staging, production, admin, or tenant segments need an active policy check between them. Protects: Internal segment and trust-boundary crossings. Placement: At internal TCP routing or proxy boundaries where source and destination segment decisions can be enforced.
  • Layer 3 - Endpoint Security: Endpoint Runtime Appliance. Use when: Use it when you need lightweight host runtime visibility and controlled active response before rolling out a full EDR program. Protects: Linux host process namespaces and critical file paths. Placement: On Linux hosts where process visibility is allowed. It runs in audit mode by default; enable enforcement deliberately.
  • Layer 4 - Application Gateway: Application WAF Appliance. Use when: Use it when the control gap is web exploit traffic reaching APIs or web apps. Protects: HTTP applications and APIs from suspicious paths, query strings, headers, request bodies, oversized bodies, and HTTP rate-limit abuse. Placement: In front of a target HTTP service as the reverse proxy. This is the WAF appliance.
  • Layer 5 - Data and Storage: Data SQL Proxy Appliance. Use when: Use it when customer data access needs query-level guardrails and evidence before a broader DLP rollout. Protects: SQL-like query paths and sensitive field access. Placement: In front of workloads that send SQL-like query strings for inspection before they reach a database-facing service.
  • Layer 6 - Security Management: Security IAM Gate Appliance. Use when: Use it when high-risk admin paths need a lightweight identity enforcement point close to the service. Protects: Privileged sessions, revoked tokens, JWT validation boundaries, and MFA-sensitive paths. Placement: In front of administrative APIs or identity-sensitive service paths that need a session validation gate.

What success looks like

The customer knows which single appliance to try first and understands that perimeter is not the WAF.

Open source bundles

الخطوة 2

Wire each appliance to BlackShield

All appliances use the same API origin and API key pattern, then sync threat intelligence or policy before reporting blocked activity as findings.

  • Perimeter TCP Edge Appliance: configure `BLACKSHIELD_API_URL`, `BLACKSHIELD_API_KEY`, `LISTEN_ADDR`, `UPSTREAM_ADDR`, `POLL_INTERVAL`, `METRICS_ADDR`, `FAIL_CLOSED`. Polls BlackShield IP threat-intel blocklists, rate-limits abusive sources, and reports dropped connections through findings ingestion.
  • Network Segmentation Appliance: configure `BLACKSHIELD_API_URL`, `BLACKSHIELD_API_KEY`, `LISTEN_ADDR`, `POLL_INTERVAL`, `METRICS_ADDR`. Syncs segmentation policy from BlackShield custom policies and reports denied segment-crossing packets.
  • Endpoint Runtime Appliance: configure `BLACKSHIELD_API_URL`, `BLACKSHIELD_API_KEY`, `POLL_INTERVAL`, `METRICS_ADDR`, `SCAN_INTERVAL`, `ENFORCEMENT_MODE`. Fetches file-hash and process indicators from BlackShield threat intelligence, audits matching processes, and can terminate them in enforce mode.
  • Application WAF Appliance: configure `BLACKSHIELD_API_URL`, `BLACKSHIELD_API_KEY`, `LISTEN_ADDR`, `UPSTREAM_URL`, `POLL_INTERVAL`, `METRICS_ADDR`, `MAX_BODY_BYTES`, `FAIL_CLOSED`. Pulls BlackShield threat signatures and blocklisted indicators, inspects HTTP requests, and posts blocked web exploitation attempts as findings.
  • Data SQL Proxy Appliance: configure `BLACKSHIELD_API_URL`, `BLACKSHIELD_API_KEY`, `LISTEN_ADDR`, `POLL_INTERVAL`, `METRICS_ADDR`. Syncs BlackShield custom data-shielding policies and reports unauthorized sensitive-field access.
  • Security IAM Gate Appliance: configure `BLACKSHIELD_API_URL`, `BLACKSHIELD_API_KEY`, `LISTEN_ADDR`, `POLL_INTERVAL`, `METRICS_ADDR`. Polls revoked-token indicators and identity policy signals from BlackShield, validates JWTs when configured, and reports blocked session attempts.

What success looks like

Every generated example uses only runtime settings supported by the matching Go entrypoint.

Open API Keys · Sign-in required

الخطوة 3

Validate signals and operating value

Treat the first deployment as a proof point: confirm the appliance starts, exposes metrics, syncs successfully, and creates useful BlackShield findings before widening the blast radius.

  • Perimeter TCP Edge Appliance: check 8081 proxy, 9090 metrics; expected telemetry includes Blocked source IP or CIDR, target listener, action, severity, rate-limit reason, and appliance heartbeat.
  • Network Segmentation Appliance: check 8082 proxy, 9090 metrics; expected telemetry includes Source segment, destination segment, payload preview, deny reason, and appliance sync health.
  • Endpoint Runtime Appliance: check 9090 metrics; expected telemetry includes Process name, PID, parent context, audit or kill action, file path events, and appliance metrics.
  • Application WAF Appliance: check 8083 proxy, 9090 metrics; expected telemetry includes HTTP path, source address, matched path/query/header/body reason, blocked action, body-size limit, and application health.
  • Data SQL Proxy Appliance: check 8084 SQL proxy, 9090 metrics; expected telemetry includes Requester, query summary, restricted fields, masking or block action, and sync status.
  • Security IAM Gate Appliance: check 8085 IAM gate, 9090 metrics; expected telemetry includes Role, resource, token fingerprint, revoked-token or JWT validation reason, MFA status, and appliance heartbeat.

What success looks like

Appliance events appear in BlackShield alongside scanner, network sensor, and security-agent evidence.

View Findings · Sign-in required

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Get the source bundle

Download the exact source files referenced on this page, or run the one-command installer to write them locally before following the deployment steps.

Go appliance Docker Compose bootstrap

Creates `deploy/blackshield-perimeter/` by default. Pass `network`, `endpoint`, `application`, `data`, or `security` as the first argument to generate a different appliance runtime.

deploy/blackshield-<appliance>/
bash
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/appliance-docker.sh) perimeter
cd deploy/blackshield-perimeter
Download source

نفّذ هذا

Perimeter TCP Edge Appliance Docker Compose

yaml
services:
  perimeter-appliance:
    image: public.ecr.aws/blackshield-security/perimeter-appliance:1.0.6
    restart: unless-stopped
    ports:
      - "8081:8081"
      - "9090:9090"
    environment:
      - BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
      - BLACKSHIELD_API_KEY=sp_xxxx
      - LISTEN_ADDR=0.0.0.0:8081
      - UPSTREAM_ADDR=10.0.1.15:80
      - POLL_INTERVAL=30s
      - METRICS_ADDR=0.0.0.0:9090
      - FAIL_CLOSED=false

Network Segmentation Appliance Docker Compose

yaml
services:
  network-appliance:
    image: public.ecr.aws/blackshield-security/network-appliance:1.0.6
    restart: unless-stopped
    ports:
      - "8082:8082"
      - "9090:9090"
    environment:
      - BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
      - BLACKSHIELD_API_KEY=sp_xxxx
      - LISTEN_ADDR=0.0.0.0:8082
      - POLL_INTERVAL=30s
      - METRICS_ADDR=0.0.0.0:9090

Endpoint Runtime Appliance Docker Compose

yaml
services:
  endpoint-appliance:
    image: public.ecr.aws/blackshield-security/endpoint-appliance:1.0.6
    restart: unless-stopped
    pid: "host"
    ports:
      - "9090:9090"
    environment:
      - BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
      - BLACKSHIELD_API_KEY=sp_xxxx
      - POLL_INTERVAL=30s
      - METRICS_ADDR=0.0.0.0:9090
      - SCAN_INTERVAL=5s
      - ENFORCEMENT_MODE=audit

Application WAF Appliance Docker Compose

yaml
services:
  application-appliance:
    image: public.ecr.aws/blackshield-security/application-appliance:1.0.6
    restart: unless-stopped
    ports:
      - "8083:8083"
      - "9090:9090"
    environment:
      - BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
      - BLACKSHIELD_API_KEY=sp_xxxx
      - LISTEN_ADDR=0.0.0.0:8083
      - UPSTREAM_URL=http://10.0.2.22:8080
      - POLL_INTERVAL=30s
      - METRICS_ADDR=0.0.0.0:9090
      - MAX_BODY_BYTES=1048576
      - FAIL_CLOSED=false

Data SQL Proxy Appliance Docker Compose

yaml
services:
  data-appliance:
    image: public.ecr.aws/blackshield-security/data-appliance:1.0.6
    restart: unless-stopped
    ports:
      - "8084:8084"
      - "9090:9090"
    environment:
      - BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
      - BLACKSHIELD_API_KEY=sp_xxxx
      - LISTEN_ADDR=0.0.0.0:8084
      - POLL_INTERVAL=30s
      - METRICS_ADDR=0.0.0.0:9090

Security IAM Gate Appliance Docker Compose

yaml
services:
  security-appliance:
    image: public.ecr.aws/blackshield-security/security-appliance:1.0.6
    restart: unless-stopped
    ports:
      - "8085:8085"
      - "9090:9090"
    environment:
      - BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
      - BLACKSHIELD_API_KEY=sp_xxxx
      - LISTEN_ADDR=0.0.0.0:8085
      - POLL_INTERVAL=30s
      - METRICS_ADDR=0.0.0.0:9090

What success looks like

  • The guide clearly says perimeter is the TCP edge proxy and application is the WAF.
  • The guide shows all six Defense-in-Depth layers and their stable public ECR image names.
  • The generated Docker Compose snippets only include runtime settings supported by the Go entrypoints.
  • Only perimeter documents `UPSTREAM_ADDR`; only application documents `UPSTREAM_URL`.
  • At least one appliance reports connector health and blocked activity into BlackShield.
  • Perimeter TCP Edge Appliance image: public.ecr.aws/blackshield-security/perimeter-appliance:1.0.6
  • Network Segmentation Appliance image: public.ecr.aws/blackshield-security/network-appliance:1.0.6
  • Endpoint Runtime Appliance image: public.ecr.aws/blackshield-security/endpoint-appliance:1.0.6
  • Application WAF Appliance image: public.ecr.aws/blackshield-security/application-appliance:1.0.6
  • Data SQL Proxy Appliance image: public.ecr.aws/blackshield-security/data-appliance:1.0.6
  • Security IAM Gate Appliance image: public.ecr.aws/blackshield-security/security-appliance:1.0.6
Deploy BlackShield Defense-in-Depth Appliances | BlackShield Docs