Public Guide

Deploy BlackShield Defense-in-Depth Appliances

Choose and run the BlackShield enforcement appliance that matches your control gap: edge firewall, microsegmentation, host runtime protection, WAF, SQL firewall, or identity-aware proxy. Audience: Founders, platform engineers, and security engineers who need clear deployment choices and working appliance examples. Typical setup time: 10-20 minutes.

reference

Use this if

Choose and run the BlackShield enforcement appliance that matches your control gap: edge firewall, microsegmentation, host runtime protection, WAF, SQL firewall, or identity-aware proxy.

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

Before You Begin

  • 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["Edge Firewall / TCP Reverse Proxy"]
  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["Edge firewall / TCP reverse proxy"]
  TcpService["Public TCP service"]

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

  Worker["Service issuing query"]
  SqlProxy["SQL firewall / database activity proxy"]
  Database["Database-facing service"]

  Operator["Admin user or service"]
  IamGate["Identity-aware proxy / admin access gateway"]
  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

Step 1

Choose the appliance that matches the control gap

Start with the boundary where a missing active control would hurt first. The edge firewall protects TCP entry points; the WAF handles HTTP inspection.

  • Perimeter and edge security: Edge Firewall / TCP Reverse Proxy. 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.
  • Network segmentation security: Microsegmentation Gateway. 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.
  • Endpoint detection and response: Host Runtime Protection. 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.
  • Application security: Web Application Firewall (WAF). 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.
  • Data access security: SQL Firewall / Database Activity Proxy. 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.
  • Identity and administrative access security: Identity-Aware Proxy / Admin Access Gateway. 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

Step 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.

  • Edge Firewall / TCP Reverse Proxy: 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.
  • Microsegmentation Gateway: 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.
  • Host Runtime Protection: 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.
  • Web Application Firewall (WAF): 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.
  • SQL Firewall / Database Activity Proxy: 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.
  • Identity-Aware Proxy / Admin Access Gateway: 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

Step 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.

  • Edge Firewall / TCP Reverse Proxy: check 8081 proxy, 9090 metrics; expected telemetry includes Blocked source IP or CIDR, target listener, action, severity, rate-limit reason, and appliance heartbeat.
  • Microsegmentation Gateway: check 8082 proxy, 9090 metrics; expected telemetry includes Source segment, destination segment, payload preview, deny reason, and appliance sync health.
  • Host Runtime Protection: check 9090 metrics; expected telemetry includes Process name, PID, parent context, audit or kill action, file path events, and appliance metrics.
  • Web Application Firewall (WAF): 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.
  • SQL Firewall / Database Activity Proxy: check 8084 SQL proxy, 9090 metrics; expected telemetry includes Requester, query summary, restricted fields, masking or block action, and sync status.
  • Identity-Aware Proxy / Admin Access Gateway: 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

Run This

Edge Firewall / TCP Reverse Proxy Docker Compose
services:
  perimeter-appliance:
    image: public.ecr.aws/blackshield-security/perimeter-appliance:1.0.8
    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
Microsegmentation Gateway Docker Compose
services:
  network-appliance:
    image: public.ecr.aws/blackshield-security/network-appliance:1.0.8
    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
Host Runtime Protection Docker Compose
services:
  endpoint-appliance:
    image: public.ecr.aws/blackshield-security/endpoint-appliance:1.0.8
    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
Web Application Firewall (WAF) Docker Compose
services:
  application-appliance:
    image: public.ecr.aws/blackshield-security/application-appliance:1.0.8
    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
SQL Firewall / Database Activity Proxy Docker Compose
services:
  data-appliance:
    image: public.ecr.aws/blackshield-security/data-appliance:1.0.8
    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
Identity-Aware Proxy / Admin Access Gateway Docker Compose
services:
  security-appliance:
    image: public.ecr.aws/blackshield-security/security-appliance:1.0.8
    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 appliance containers start up cleanly without configuration errors or continuous restarts.
  • The perimeter appliance successfully forwards TCP connections to the configured backend.
  • The application appliance (WAF) successfully intercepts and filters HTTP requests using the OWASP CRS.
  • Data shielding and IAM token validation policies are actively enforced on database and security gates.
  • Appliance heartbeats, connection metrics, and blocked events are visible on the BlackShield dashboard.
Deploy BlackShield Defense-in-Depth Appliances | BlackShield Docs