> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Security

> Network policies, SSRF protection, TLS configuration, and network segmentation for CRAFT.

# Network Security

CRAFT implements defense-in-depth network security including TLS encryption, SSRF protection, Kubernetes network policies, and DNS security. This page covers the network security architecture and configuration.

## TLS Configuration

All external and internal communication is encrypted with TLS:

| Channel               | Protocol | Minimum Version | Certificate Management                                            |
| --------------------- | -------- | --------------- | ----------------------------------------------------------------- |
| Client to API gateway | HTTPS    | TLS 1.3         | Managed certificates (Let's Encrypt, cloud-managed, or custom CA) |
| Service to service    | HTTPS    | TLS 1.2         | Internal CA or service mesh                                       |
| Service to PostgreSQL | TLS      | TLS 1.2         | Cloud-managed or custom CA                                        |
| Service to Redis      | TLS      | TLS 1.2         | Cloud-managed                                                     |
| Keycloak to IdP       | HTTPS    | TLS 1.2         | IdP-managed certificates                                          |
| Webhook deliveries    | HTTPS    | TLS 1.2         | Target server certificates                                        |

<Note>
  TLS 1.0 and 1.1 are not supported. The platform enforces TLS 1.2 as a minimum and recommends TLS 1.3 for all external connections.
</Note>

## SSRF Protection

All outbound HTTP requests are protected against Server-Side Request Forgery (SSRF) attacks. This includes JWS `jku` fetch, health checks, webhook delivery (planned), and crawler operations.

### Protection Layers

| Protection               | Implementation                                                                                                                                                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Private IP blocking**  | Resolved IPs validated against RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (fc00::/7), link-local (169.254.0.0/16, fe80::/10), and loopback (127.0.0.0/8, ::1) |
| **DNS pinning**          | DNS resolution performed before connection; resolved IP pinned to prevent TOCTOU rebinding attacks                                                                                |
| **HTTPS enforcement**    | `jku` URLs must use HTTPS; webhook targets must use HTTPS in production (when implemented)                                                                                        |
| **Redirect limiting**    | At most 2 redirects followed, with IP re-validation after each redirect                                                                                                           |
| **Domain allowlists**    | Configurable per feature (e.g., `jku` domains, crawl domains)                                                                                                                     |
| **Response size limits** | Crawler responses limited to 1 MB                                                                                                                                                 |
| **Timeout enforcement**  | `jku` fetch: 5 seconds; health checks: 10 seconds (configurable)                                                                                                                  |

### Per-Context Behavior

Different outbound request types apply SSRF rules differently:

| Context          | Private IPs              | SSRF Check | Notes                                                                   |
| ---------------- | ------------------------ | ---------- | ----------------------------------------------------------------------- |
| Health checks    | Skip with UNKNOWN status | Yes        | Cards with private-IP endpoints are accepted; health checks are skipped |
| JWS `jku` fetch  | Reject                   | Yes        | HTTPS required; domain allowlist applies                                |
| Crawler          | Reject                   | Yes        | Admin-configured domains only                                           |
| Webhook delivery | Reject                   | Yes        | HTTPS required in production; fire-and-forget                           |

## Kubernetes Network Policies

The platform uses Kubernetes NetworkPolicies to restrict pod-to-pod communication:

```yaml theme={null}
# Example: Governance service network policy
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: governance-netpol
spec:
  podSelector:
    matchLabels:
      app: governance
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: assets
        - podSelector:
            matchLabels:
              app: utils
      ports:
        - port: 8000
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: keycloak
      ports:
        - port: 8080
    - to:
        - podSelector:
            matchLabels:
              app: openfga
      ports:
        - port: 8080
    - to:
        - podSelector:
            matchLabels:
              app: postgresql
      ports:
        - port: 5432
```

### Network Segmentation

The platform services are segmented into security zones:

<AccordionGroup>
  <Accordion title="External Zone">
    Receives traffic from external clients via the ingress controller or API gateway. Only the API endpoints and Keycloak login pages are exposed externally.
  </Accordion>

  <Accordion title="Application Zone">
    Contains the platform services (Governance, Assets, Utils) and solution services (Data Insights, Data Governance). Services communicate via internal cluster networking with TLS.
  </Accordion>

  <Accordion title="Data Zone">
    Contains PostgreSQL, Redis, and other data stores. Only accessible from the Application Zone. No direct external access is permitted.
  </Accordion>

  <Accordion title="Identity Zone">
    Contains Keycloak and OpenFGA. Keycloak is partially exposed (login pages) while OpenFGA is internal-only.
  </Accordion>
</AccordionGroup>

## Ingress Security

### Ingress Controller Configuration

The platform's ingress controller (NGINX or cloud-managed) enforces:

| Setting                   | Value               | Purpose                                                                                     |
| ------------------------- | ------------------- | ------------------------------------------------------------------------------------------- |
| `ssl-redirect`            | `true`              | Force HTTPS for all connections                                                             |
| `hsts-max-age`            | `31536000`          | HTTP Strict Transport Security (1 year)                                                     |
| `hsts-include-subdomains` | `true`              | Apply HSTS to all subdomains                                                                |
| `proxy-body-size`         | `50m`               | Limit request body size (matches skill package upload limit)                                |
| `rate-limiting`           | Customer-configured | Per-route rate limiting at the ingress level (must be configured by deploying organization) |

### Web Application Firewall (WAF)

WAF protection is recommended for all production deployments, especially those processing PHI, financial data, or sensitive enterprise data:

* **GCP**: Cloud Armor security policies with OWASP Top 10 managed rules
* **AWS**: AWS WAF with AWS Managed Rules (Core Rule Set, Known Bad Inputs)
* **Azure**: Azure Front Door or Application Gateway WAF with OWASP 3.2 ruleset

<Warning>
  Deployments without WAF should document this as an accepted risk in their security posture. At minimum, enable the cloud provider's managed OWASP Top 10 rule group and IP reputation-based blocking.
</Warning>

## DNS Security

| Protection           | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| **DNSSEC**           | Recommended for external DNS zones to prevent DNS spoofing  |
| **Internal DNS**     | Kubernetes CoreDNS for service discovery within the cluster |
| **DNS pinning**      | SSRF protection pins resolved IPs to prevent DNS rebinding  |
| **TXT verification** | Agent domain verification via DNS TXT records               |

## Service Mesh (Optional)

For zero-trust deployments, the platform supports service mesh integration:

<Tabs>
  <Tab title="Istio">
    * Automatic mTLS between all pods
    * Authorization policies for fine-grained access control
    * Traffic management and observability
    * PeerAuthentication for strict mTLS enforcement
  </Tab>

  <Tab title="Linkerd">
    * Automatic mTLS with minimal configuration
    * Lightweight proxy with low resource overhead
    * Service profiles for per-route reliability settings
  </Tab>
</Tabs>

## Webhook Security

When released, outbound webhook payloads will include security headers for integrity verification:

| Header                | Description                              |
| --------------------- | ---------------------------------------- |
| `X-Webhook-Id`        | Unique delivery ID for idempotency       |
| `X-Webhook-Timestamp` | ISO 8601 timestamp for replay protection |
| `X-Webhook-Signature` | HMAC-SHA256 signature of the payload     |

Receivers should:

1. Verify the HMAC-SHA256 signature using the shared secret
2. Reject payloads older than 5 minutes (replay protection)
3. Use the delivery ID for idempotent processing

<Tip>
  Webhook secrets support rotation with a 24-hour overlap period. During rotation, both the old and new secrets are valid for signature verification.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused between services">
    Check Kubernetes NetworkPolicies. Verify the source pod has egress rules allowing traffic to the destination pod on the correct port. Use `kubectl describe networkpolicy` to inspect active policies.
  </Accordion>

  <Accordion title="SSRF check blocking legitimate URLs">
    Verify the target URL resolves to a public IP address. If the target is behind a private DNS, add the domain to the appropriate allowlist. Health checks for agents with private IPs return UNKNOWN status by design.
  </Accordion>

  <Accordion title="TLS handshake failures">
    Check certificate validity and chain completeness. Verify the server supports TLS 1.2 or higher. For internal services, ensure the internal CA certificate is trusted by all pods.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/security/authentication">
    Review the authentication architecture and token management.
  </Card>

  <Card title="Data Classification" icon="tags" href="/security/data-classification">
    Understand encryption requirements by data classification level.
  </Card>

  <Card title="Helm Configuration" icon="dharmachakra" href="/deployment/helm/configuration">
    Configure network-related Helm values for your deployment.
  </Card>

  <Card title="Networking" icon="network-wired" href="/deployment/infrastructure/networking">
    Infrastructure-level networking configuration for Kubernetes.
  </Card>
</CardGroup>