BLACKSHIELD

Guia público

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. Público: Founders, platform engineers, and security engineers who need clear deployment choices and working appliance examples. Tempo típico de configuração: 10-20 minutes.

reference

Use isto se

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

Antes de começar

  • 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

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

Como é o sucesso

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

Open source bundles

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

Como é o sucesso

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

Open API Keys · Requer login

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

Como é o sucesso

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

View Findings · Requer login

Apenas para demonstração

Esta configuração foi concebida para facilitar a utilização. Para implementar clientes de scanner em escala, planeie a sua arquitetura de implementação adequadamente ou contacte-nos para obter as melhores práticas empresariais.

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

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
Descarregar fonte

Executar isto

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

Como é o sucesso

  • 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 | Documentação BlackShield