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

# AWS Integration & Proof of Value

> Three ways to correlate internet-facing traffic on AWS (direct EIP, NLB, ALB, AWS WAF, CloudFront) with the OneFirewall Crime Score, for SOC 2 cloud-native environments

## Scope

This page describes how to run a OneFirewall Proof of Value (PoV) in an AWS-native, SOC 2-audited environment, and how the same building blocks carry over to production.

The PoV question stays the same as in the [standard PoV](https://docs.onefirewall.com/essentials/pov.md):

> Which internet sources that the OneFirewall Alliance already scores as malicious reached our exposed surfaces, through which surface, and what did our existing controls do with them?

On AWS that question has to be answered per **ingress surface**, because each surface sees a different client IP and writes a different log:

| Surface | Client IP visible at the surface | Telemetry source | Edge action field |
| - | - | - | - |
| EC2 / ENI with Elastic IP (direct exposure) | True client IP | VPC Flow Logs on the ENI | `action` = `ACCEPT` / `REJECT` (Security Group / NACL) |
| Network Load Balancer (NLB) | True client IP (no TCP termination; client IP preservation on by default for instance targets) | VPC Flow Logs on the NLB ENIs; NLB access logs exist **only for TLS listeners** | `ACCEPT` / `REJECT` |
| Application Load Balancer (ALB) | TCP peer. That is the client, or a CloudFront edge IP if the ALB sits behind CloudFront | ALB access logs (`client:port`, `target:port`, `elb_status_code`) and VPC Flow Logs on the ALB ENIs | HTTP status, `actions_executed`, whether a target was selected |
| AWS WAF (on ALB, CloudFront, API Gateway, AppSync, Cognito) | `httpRequest.clientIp`, which is the TCP peer of the protected resource | AWS WAF logs (S3 bucket name must start with `aws-waf-logs-`, or CloudWatch Logs, or Firehose) | `action` = `ALLOW` / `BLOCK` / `COUNT` / `CAPTCHA` / `CHALLENGE` |
| CloudFront | True client IP (`c-ip`) | CloudFront standard logs | `x-edge-result-type` |

> [!WARNING]
>
> If an ALB is fronted by CloudFront, the ALB access log and any WAF attached to the **ALB** see CloudFront edge IPs, not attackers. Correlate on the CloudFront log (`c-ip`) or on the WebACL attached to the **CloudFront distribution**. The `IS_CDN` column of the OneFirewall feed and `/info/cdn/list` are used below to keep CDN edge IPs out of the attacker set.

```mermaid theme={null}
graph LR
    I((Internet)) --> CF[CloudFront<br/>+ WebACL CLOUDFRONT scope]
    I --> EIP[EC2 ENI + EIP<br/>direct exposure]
    I --> NLB[NLB]
    I --> ALB[ALB<br/>+ WebACL REGIONAL scope]
    CF --> ALB
    ALB --> T1[Targets]
    NLB --> T2[Targets]
    CF -. standard logs .-> S3[(Log archive S3)]
    ALB -. access logs .-> S3
    ALB -. WAF logs .-> S3
    EIP -. VPC Flow Logs .-> S3
    NLB -. VPC Flow Logs .-> S3
    ALB -. VPC Flow Logs .-> S3
```

***

## OneFirewall API used in this page

Base URL: `https://app.onefirewall.com/api/v1`. All calls carry `Authorization: Bearer <JWT>`, generated from the profile page (see [Authorization](https://docs.onefirewall.com/api-reference/authorization.md)). Only outbound HTTPS 443 to this host is needed. No inbound connectivity from OneFirewall to AWS is used by any of the three methods.

| Endpoint | Use in the PoV | Response |
| - | - | - |
| `GET /flat/{min_score}?list=NO` | Bulk snapshot of every scored IPv4 at or above `min_score`. Primary join table. | CSV: `IPv4,LiveScore,Members,Reports,LastUpdate,AS,ASN,CDN,Reverse,IS_CDN` |
| `GET /flat/{min_score}?list=YES` | Flat comma-separated IP list for IP-set sync (Method 3) | `ip,ip,ip,...` |
| `GET /ipv4/{min_score}?format=CSV&show_score=yes` | Real-time scored list (v3.2 scoring). Paginated: repeat the call with `page=<next_page>` while the `next_page` response header is present. About 6× slower than `/flat`. | CSV with score and manual/score-based flag |
| `GET /intel/{ipv4}` | Drill-down for the report: score, reports, members, MITRE, agents | JSON |
| `GET /ips/{ipv4}` | Per-IP raw record (`score`, `info.members`, `info.events`, `info.sources`, `ip_info.asn`, `ip_info.country`) | JSON |
| `GET /info/cdn/list` | Well-known CDN edge ranges, to exclude from the attacker set | JSON `[{name, addresses[]}]` |
| `GET /version` | Health check (no auth required) | JSON |

```bash theme={null}
export OFA_TOKEN='<jwt>'
curl -s -H "Authorization: Bearer $OFA_TOKEN" \
  "https://app.onefirewall.com/api/v1/flat/2?list=NO" -o ofa_flat.csv
head -3 ofa_flat.csv
# IPv4,LiveScore,Members,Reports,LastUpdate,AS,ASN,CDN,Reverse,IS_CDN
# X.Y.Z.W,216,3,21,2023-04-29T04:43:54.000Z,AS....,<AS name>,<CDN>,<rDNS>,
```

### Score semantics relevant to correlation

* Range 0–1000. `0` means never observed. See [Crime Score](https://docs.onefirewall.com/essentials/crime-score.md).
* Severity bands used in PoV reports: **Low** 1–60, **Medium** 60–120, **High** 120–175, **Critical** 175–1000.
* IPv4 scores decay over time. The decay function is returned in the `header.eval` field of `/ips` responses (`score = s0 / (1 + exp((3/s0) * (t/3600 - 2.5*s0)))`). The score of an IP on day 10 is therefore not the score it had when it hit you on day 1.
* **Take a dated snapshot of `/flat` at least daily, and join each event to the snapshot of the event's date.** Do not re-score 10 days of logs against a single end-of-PoV snapshot.
* Enforcement guidance (not needed for a read-only PoV): start at score ≥ 400 and lower it over time. The Alliance-validated baseline is ≥ 190.

***

## Choosing a method

| | Method 1: Customer-run analysis script | Method 2: Feed into your own data lake (zero footprint) | Method 3: AWS WAF / Network Firewall in shadow mode |
| - | - | - | - |
| What gets deployed in your AWS account | Nothing permanent. A script run on a customer-owned host with a read-only S3 role. | 1 Lambda, 1 S3 prefix, Athena tables | 1 Lambda, WAF IP sets + COUNT rules, optionally Network Firewall `alert` rules |
| OneFirewall staff access to AWS | None | None | None |
| Data leaving the account | None. Logs are processed on the customer's host. Only authenticated GETs to the API (plus optional per-IP enrichment lookups). | None. Only authenticated GETs to the API. | None |
| Surfaces covered | EIP, NLB, ALB, WAF, CloudFront (whatever is in S3) | Same as Method 1 | WAF-protected HTTP surfaces. EIP/NLB only if Network Firewall is already in the ingress path. |
| Output | PDF report (executive summary + top malicious events) and full CSV, on the customer's host | Athena query results (CSV) in your account | WAF labels and metrics, WAF logs, and Network Firewall alert logs |
| Production path | Re-run on a schedule, or move to Method 2/3, or deploy WCF/OnPrem | Scheduled feed + SIEM correlation | Flip `COUNT` → `BLOCK` / `alert` → `drop` |
| Typical PoV effort | \~0.5 day (IAM role + config), one script run per report | \~0.5 day | \~0.5 day (WAF), more if Network Firewall routing is required |

Methods 1 and 2 are **passive** and read logs only. Method 3 places OneFirewall data inside the request path, in a non-blocking mode. Methods can be combined: Method 2 for retrospective analysis across all surfaces, and Method 3 for "what would WAF have blocked" evidence.

***

## Prerequisite: log sources

All three methods depend on the same AWS logs. In an AWS Organizations / Control Tower setup they usually land in the **Log Archive** account. Enable whatever is not already on, at least 24 h before the PoV analysis window starts.

**1. Build the inventory of internet-facing ENIs**

The inventory maps each flow-log `interface_id` to a surface (direct EIP, NLB, ALB). Run it in every account and Region in scope:

```bash theme={null}
aws ec2 describe-network-interfaces --output json \
| jq -r '.NetworkInterfaces[]
    | select(.Association.PublicIp != null)
    | [ .NetworkInterfaceId,
        ( if   (.Description | startswith("ELB app/")) then "ALB"
          elif (.Description | startswith("ELB net/")) then "NLB"
          elif (.InterfaceType == "nat_gateway")       then "NATGW"
          else "EIP_DIRECT" end ),
        ( .Attachment.InstanceId // .Description ),
        .Association.PublicIp,
        .VpcId ]
    | @csv' > eni_inventory.csv
```

Upload `eni_inventory.csv` to `s3://<analysis-bucket>/ofa-pov/eni_inventory/`. `NATGW` rows are kept for completeness but excluded from ingress analysis.

> [!NOTE]
>
> ENIs change when load balancers scale. Re-run the inventory daily during the PoV, or drive it from EventBridge on `CreateNetworkInterface`.

**2. VPC Flow Logs (EIP, NLB, ALB ENIs)**

Use a custom format so that direction and packet-level addresses are present, Parquet output with Hive-compatible partitions, and a 60 s aggregation interval:

```bash theme={null}
aws ec2 create-flow-logs \
  --resource-type VPC --resource-ids vpc-0123456789abcdef0 \
  --traffic-type ALL \
  --log-destination-type s3 \
  --log-destination arn:aws:s3:::<log-archive-bucket>/vpcflow/ \
  --max-aggregation-interval 60 \
  --destination-options FileFormat=parquet,HiveCompatiblePartitions=true,PerHourPartition=false \
  --log-format '${version} ${account-id} ${interface-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${packets} ${bytes} ${start} ${end} ${action} ${log-status} ${vpc-id} ${instance-id} ${tcp-flags} ${pkt-srcaddr} ${pkt-dstaddr} ${flow-direction}'
```

* `action=REJECT` means the Security Group or NACL dropped the flow. `ACCEPT` means it reached the ENI.
* For an ALB ENI, `ACCEPT` means "TCP accepted by the ALB". It does **not** mean "reached a target", and it is still `ACCEPT` when WAF later returns 403. Use ALB/WAF logs for the L7 outcome.

**3. ALB access logs**

Enable them on each internet-facing ALB (`access_logs.s3.enabled=true`). Relevant fields: `client:port`, `target:port` (`-` when no target was selected), `elb_status_code`, `target_status_code`, `request`, `user_agent`, `actions_executed` (contains `waf` when WAF evaluated the request).

> [!WARNING]
>
> At the time of writing, ALB access log delivery supports SSE-S3 only. If your Log Archive bucket policy enforces SSE-KMS, deliver ALB logs to a dedicated SSE-S3 bucket with the same retention and access controls.

**4. AWS WAF logs**

Log every WebACL in scope to S3 (bucket name prefixed `aws-waf-logs-`) or through Firehose. Relevant fields: `httpRequest.clientIp`, `httpRequest.country`, `action`, `terminatingRuleId`, `nonTerminatingMatchingRules`, `labels`, `webaclId`. Do **not** enable a logging filter that drops `ALLOW` records, because the allowed requests are the point of the PoV.

**5. CloudFront standard logs (if CloudFront fronts an ALB)**

Required to recover the real client IP (`c-ip`) for CloudFront → ALB paths.

***

## Method 1: Customer-run analysis script (read-only S3 access)

The analysis runs entirely in an environment that the customer owns and operates. OneFirewall deploys nothing and has no access to the AWS account. The customer runs a script, supplied by the OneFirewall team, that does the following:

1. Downloads the ingress logs for the PoV window from S3 using a read-only identity.
2. Downloads the scored feed from the OneFirewall API.
3. Matches every inbound connection/request against the Crime Score, per surface.
4. Writes a **PDF report** (executive summary + top malicious events) and a CSV of the full results, on the customer's host.

The customer decides whether to share the PDF with OneFirewall for the readout.

```mermaid theme={null}
graph LR
    subgraph LogArchive[Log Archive account]
      B1[(VPC Flow Logs)]
      B2[(ALB logs)]
      B3[(WAF logs)]
      B4[(CloudFront logs)]
    end
    subgraph Customer[Customer-controlled environment]
      H[Analysis host<br/>OneFirewall PoV script]
      R[PDF report + CSV]
    end
    B1 & B2 & B3 & B4 -->|s3:GetObject / s3:ListBucket<br/>read-only role| H
    H -->|HTTPS 443, GET only| OFA[app.onefirewall.com/api/v1<br/>scored feed]
    H --> R
    R -. shared by customer for readout .-> RO[OneFirewall readout]
```

### Where it runs

Any host the customer controls that can assume the read-only role, for example:

* an EC2 instance or ECS/Fargate task in a security tooling account,
* an existing analyst jump host or workstation,
* a CI runner in the customer's own pipeline.

| Item | Requirement |
| - | - |
| Runtime | Python 3.10+ (dependencies listed in the script's `requirements.txt`) or the container image supplied with the script |
| Disk | Enough for the downloaded logs for the window. Flow logs in Parquet are the largest input, so estimate from `aws s3 ls --summarize --recursive` on the prefixes. |
| Network | HTTPS 443 to S3 (an S3 gateway endpoint is preferred) and to `app.onefirewall.com`. No inbound connectivity. |
| Identity | A read-only IAM role on the log buckets (see below), assumed through the customer's normal SSO / instance profile |
| Secret | OneFirewall API token, from Secrets Manager or an environment variable. Never stored in the config file. |

### Script supply chain

The script is delivered as source code. Before running it, the customer can review it and approve it under their normal software intake process:

* Versioned release with a published SHA-256 checksum; verify it before running.
* No outbound destinations other than S3 and `app.onefirewall.com/api/v1`, which the code review can confirm.
* No telemetry, no upload of logs or results. The only data sent to OneFirewall are authenticated GET requests for the feed, plus optional per-IP `/intel/{ipv4}` or `/ips/{ipv4}` lookups for the top-N attacker IPs used to enrich the report (country, ASN, alliance members). The enrichment lookups can be disabled.

### Read-only IAM role

Attach to the role that the analysis host assumes. Read-only on the log prefixes, plus KMS decrypt if the buckets use SSE-KMS:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadIngressLogs",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::<log-archive-bucket>",
        "arn:aws:s3:::<log-archive-bucket>/vpcflow/*",
        "arn:aws:s3:::<log-archive-bucket>/alb/*",
        "arn:aws:s3:::aws-waf-logs-<suffix>",
        "arn:aws:s3:::aws-waf-logs-<suffix>/*"
      ]
    },
    {
      "Sid": "DecryptLogObjects",
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:<region>:<log-archive-account>:key/<key-id>",
      "Condition": { "StringEquals": { "kms:ViaService": "s3.<region>.amazonaws.com" } }
    },
    {
      "Sid": "ReadEniInventory",
      "Effect": "Allow",
      "Action": "ec2:DescribeNetworkInterfaces",
      "Resource": "*"
    }
  ]
}
```

If the logs live in a separate Log Archive account, the bucket policy and KMS key policy there must also name this role as principal. `ec2:DescribeNetworkInterfaces` is only needed if the script builds the ENI inventory itself. Otherwise, provide `eni_inventory.csv` from the prerequisite step. More authentication options (IAM Roles Anywhere for non-AWS hosts) are in [S3 Log Processing](https://docs.onefirewall.com/essentials/logs-events/s3-log-processing.md).

### Running it

The exact command-line interface ships with the script's README. The example below shows the inputs it needs:

```yaml pov-config.yaml theme={null}
window:
  start: 2026-11-01T00:00:00Z
  end:   2026-11-11T00:00:00Z
sources:
  vpc_flow:   s3://<log-archive-bucket>/vpcflow/AWSLogs/
  alb:        s3://<log-archive-bucket>/alb/AWSLogs/
  waf:        s3://aws-waf-logs-<suffix>/
  cloudfront: s3://<cf-log-bucket>/            # optional
eni_inventory: ./eni_inventory.csv            # or let the script describe ENIs
onefirewall:
  api: https://app.onefirewall.com/api/v1
  token_env: OFA_TOKEN                        # or secrets_manager: <secret-id>
  min_score: 2
  enrich_top_n: 50                            # 0 disables per-IP lookups
report:
  top_events: 100
  output_dir: ./ofa-pov-report/
```

```bash theme={null}
export OFA_TOKEN="$(aws secretsmanager get-secret-value --secret-id ofa/pov-token --query SecretString --output text)"
sha256sum -c ofa-pov-<version>.sha256
python ofa_pov.py --config pov-config.yaml
# ./ofa-pov-report/OneFirewall-PoV-<account>-<start>_<end>.pdf
# ./ofa-pov-report/malicious_events.csv
```

> [!NOTE]
>
> **Score at time of event.** Crime Scores decay, so scoring 10-day-old logs against a single feed snapshot taken at the end of the window under-reports actors that were active early on. Take a daily feed snapshot during the window (cron or EventBridge on the same host, or the feed snapshot Lambda from Method 2) and point the script at the snapshot directory, so that each event is matched against the snapshot of its own day. If only one end-of-window snapshot exists, the report says so in its methodology section.

### Processing logic

Per log record, the script:

1. Normalises to `(ts, client_ip, surface, resource, edge_action, dst_port, http_status, reached_backend)`. Surfaces are `EIP_DIRECT`, `NLB` and `ALB` (L4, from flow logs plus the ENI inventory), `ALB_L7`, `WAF` and `CLOUDFRONT`. Only `flow_direction = ingress` is kept.
2. Drops well-known CDN edge IPs (`IS_CDN` in the feed, `/info/cdn/list`). For CloudFront-fronted ALBs, it uses `c-ip` from CloudFront logs as the client.
3. Joins `client_ip` to the feed snapshot of the event's day. Severity bands: Low 1–60, Medium 60–120, High 120–175, Critical 175–1000.
4. Aggregates per actor, surface and severity, and flags **allowed** events (`ACCEPT`, WAF `ALLOW`/`COUNT`, ALB forwarded to a target).

The logic is the same as the Athena queries in Method 2, so the two methods give comparable numbers.

### PDF report contents

**Executive summary** (one page):

| Metric | Definition |
| - | - |
| Analysis window | Start/end, accounts and Regions, surfaces in scope |
| Inbound events analysed | All normalised ingress records |
| Allowed events | Records that passed the edge control (SG/NACL `ACCEPT`, WAF `ALLOW`, ALB forwarded) |
| Malicious events / unique actors | Records whose source has a Crime Score ≥ 1 |
| Malicious **and allowed** | The key PoV figure, as a count and as % of allowed traffic |
| By severity | Low / Medium / High / Critical: events, unique actors, allowed |
| By surface | EIP\_DIRECT / NLB / ALB / WAF / CloudFront: malicious allowed, reached backend |
| Origin bypass | High/Critical actors that reached an L4 surface of an application meant to be reachable only through CloudFront + WAF |
| WAF gap | Critical actors whose requests the existing WebACL allowed |
| Top source countries / ASNs | From the per-IP enrichment |

**Top malicious events** (the top N by score, then by event count):

| Column | Source |
| - | - |
| First / last seen | Log timestamps |
| Source IP | Log |
| Crime Score, severity | OneFirewall feed (day-of-event snapshot) |
| Alliance members / reports | Feed `Members`, `Reports` |
| Surface, resource | ENI inventory, ALB name, WebACL ID |
| Destination port / HTTP status / WAF rule | Log |
| Action at edge, reached backend | Log |
| Country, ASN | `/ips/{ipv4}` or `/intel/{ipv4}` enrichment |

**Appendix:** methodology, log sources and record counts per source, feed snapshot dates, script version and checksum.

The CSV contains every malicious event, not only the top N, for import into the SIEM or for the auditor's evidence folder.

***

## Method 2: OneFirewall feed in your own data lake (zero footprint)

Nothing from OneFirewall runs in the account and nobody from OneFirewall has access. A scheduled Lambda pulls a dated snapshot of the scored feed into S3, and the correlation is a set of Athena queries over logs you already keep. This method is the easiest one to clear with a SOC 2 change board and vendor-risk review, and it is fully reproducible by your own auditors.

### 2.1 Feed snapshot Lambda

Runtime Python 3.12, scheduled daily or hourly by EventBridge Scheduler. The token is stored in Secrets Manager.

```python ofa_feed_snapshot.py theme={null}
import os, datetime, urllib.request, boto3

API = "https://app.onefirewall.com/api/v1"
MIN_SCORE = os.environ.get("MIN_SCORE", "2")          # lowest value /flat accepts
BUCKET = os.environ["BUCKET"]                          # e.g. sec-analytics-<acct>
PREFIX = os.environ.get("PREFIX", "ofa-pov/feed")
SECRET_ID = os.environ["OFA_TOKEN_SECRET"]

s3 = boto3.client("s3")
token = boto3.client("secretsmanager").get_secret_value(SecretId=SECRET_ID)["SecretString"]

def handler(event, context):
    req = urllib.request.Request(
        f"{API}/flat/{MIN_SCORE}?list=NO",
        headers={"Authorization": f"Bearer {token}"},
    )
    with urllib.request.urlopen(req, timeout=120) as r:
        body = r.read()
    now = datetime.datetime.now(datetime.timezone.utc)
    key = f"{PREFIX}/dt={now:%Y-%m-%d}/flat_{now:%H%M}.csv"
    s3.put_object(Bucket=BUCKET, Key=key, Body=body,
                  ServerSideEncryption="aws:kms")
    return {"key": key, "bytes": len(body)}
```

Lambda execution role: `secretsmanager:GetSecretValue` on the one secret, `s3:PutObject` on the feed prefix, `kms:GenerateDataKey` on the bucket key. The function needs egress (a VPC with NAT/proxy allow-listing `app.onefirewall.com`, or no VPC).

### 2.2 Athena tables

```sql theme={null}
-- OneFirewall feed snapshots (one partition per day)
CREATE EXTERNAL TABLE ofa_feed (
  ip           string,
  live_score   int,
  members      int,
  reports      int,
  last_update  string,
  as_number    string,
  as_name      string,
  cdn          string,
  reverse_dns  string,
  is_cdn       string
)
PARTITIONED BY (dt string)
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.OpenCSVSerde'
LOCATION 's3://<analysis-bucket>/ofa-pov/feed/'
TBLPROPERTIES ('skip.header.line.count'='1');

-- ENI inventory produced by the prerequisite step
CREATE EXTERNAL TABLE eni_inventory (
  interface_id string, surface string, resource string, public_ip string, vpc_id string
)
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.OpenCSVSerde'
LOCATION 's3://<analysis-bucket>/ofa-pov/eni_inventory/';

-- VPC Flow Logs, Parquet, Hive-compatible partitions, custom format above
CREATE EXTERNAL TABLE vpc_flow (
  version int, account_id string, interface_id string,
  srcaddr string, dstaddr string, srcport int, dstport int, protocol bigint,
  packets bigint, bytes bigint, start bigint, `end` bigint,
  action string, log_status string, vpc_id string, instance_id string,
  tcp_flags int, pkt_srcaddr string, pkt_dstaddr string, flow_direction string
)
PARTITIONED BY (`aws-account-id` string, `aws-service` string, `aws-region` string,
                `year` string, `month` string, `day` string)
STORED AS PARQUET
LOCATION 's3://<log-archive-bucket>/vpcflow/AWSLogs/';
```

Load partitions with `MSCK REPAIR TABLE` (or partition projection). For ALB logs use the `alb_access_logs` DDL from the AWS documentation ("Querying Application Load Balancer logs"). For WAF logs use the `waf_logs` DDL from "Querying AWS WAF logs". The queries below use those AWS column names (`client_ip`, `target_ip`, `elb_status_code`, `httprequest.clientip`, `labels`, ...).

### 2.3 Normalised ingress view

```sql theme={null}
CREATE OR REPLACE VIEW ingress_events AS
-- L3/L4: direct EIP, NLB and ALB ENIs
SELECT
  from_unixtime(f.start)                       AS ts,
  f.srcaddr                                    AS client_ip,
  i.surface                                    AS surface,      -- EIP_DIRECT | NLB | ALB
  i.resource                                   AS resource,
  f.action                                     AS edge_action,  -- ACCEPT | REJECT
  f.dstport                                    AS dst_port,
  CAST(NULL AS integer)                        AS http_status,
  CASE WHEN i.surface IN ('EIP_DIRECT','NLB') AND f.action = 'ACCEPT'
       THEN true ELSE NULL END                 AS reached_backend
FROM vpc_flow f
JOIN eni_inventory i ON f.interface_id = i.interface_id
WHERE f.flow_direction = 'ingress'
  AND i.surface IN ('EIP_DIRECT','NLB','ALB')

UNION ALL
-- L7: ALB
SELECT
  from_iso8601_timestamp(a.time), a.client_ip, 'ALB_L7', a.elb,
  CASE WHEN a.target_ip IN ('', '-') THEN 'NOT_FORWARDED' ELSE 'FORWARDED' END,
  CAST(NULL AS integer), a.elb_status_code,
  NOT (a.target_ip IN ('', '-'))
FROM alb_access_logs a

UNION ALL
-- L7: AWS WAF
SELECT
  from_unixtime(w.timestamp / 1000), w.httprequest.clientip, 'WAF', w.webaclid,
  w.action, CAST(NULL AS integer), CAST(NULL AS integer),
  CASE WHEN w.action IN ('ALLOW','COUNT') THEN true ELSE false END
FROM waf_logs w;
```

> [!NOTE]
>
> The ALB access log carries no listener-port column. Derive it from the `request` URL if you need it. If an ALB is behind CloudFront, filter out its `ALB_L7` rows whose `client_ip` falls in the CloudFront ranges (`is_cdn` in the feed, or `/info/cdn/list`) and add a CloudFront branch on `c-ip` instead.

### 2.4 Correlation

Join each event to the feed snapshot of **the same day**, excluding well-known CDN edges:

```sql theme={null}
CREATE OR REPLACE VIEW ingress_scored AS
SELECT e.*,
       o.live_score, o.members, o.reports, o.as_number, o.as_name,
       CASE WHEN o.live_score >= 175 THEN 'CRITICAL'
            WHEN o.live_score >= 120 THEN 'HIGH'
            WHEN o.live_score >=  60 THEN 'MEDIUM'
            ELSE 'LOW' END AS severity
FROM ingress_events e
JOIN ofa_feed o
  ON  o.ip = e.client_ip
  AND o.dt = date_format(e.ts, '%Y-%m-%d')
WHERE coalesce(o.is_cdn, '') = '';
```

**Q1: exposure summary per surface and severity**

```sql theme={null}
SELECT surface, severity,
       count(*)                                         AS events,
       count(DISTINCT client_ip)                        AS actors,
       count_if(edge_action IN ('ACCEPT','ALLOW','COUNT','FORWARDED')) AS allowed_events,
       count_if(reached_backend)                        AS reached_backend_events
FROM ingress_scored
WHERE ts >= current_timestamp - INTERVAL '10' DAY
GROUP BY 1, 2
ORDER BY 1, CASE severity WHEN 'CRITICAL' THEN 1 WHEN 'HIGH' THEN 2 WHEN 'MEDIUM' THEN 3 ELSE 4 END;
```

**Q2: allowed malicious actors (the PoV CSV)**

```sql theme={null}
SELECT client_ip, max(live_score) AS score,
       CASE WHEN max(live_score) >= 175 THEN 'CRITICAL'
            WHEN max(live_score) >= 120 THEN 'HIGH'
            WHEN max(live_score) >=  60 THEN 'MEDIUM'
            ELSE 'LOW' END AS severity,
       max(members) AS alliance_members, max(as_number) AS asn, max(as_name) AS as_name,
       array_join(array_agg(DISTINCT surface), '|')  AS surfaces,
       array_join(array_agg(DISTINCT resource), '|') AS resources,
       min(ts) AS first_seen, max(ts) AS last_seen,
       count(*) AS events,
       count_if(reached_backend) AS reached_backend_events
FROM ingress_scored
WHERE edge_action IN ('ACCEPT','ALLOW','COUNT','FORWARDED')
GROUP BY client_ip
ORDER BY score DESC, events DESC;
```

**Q3: multi-surface actors and WAF bypass.** These are actors scored High/Critical that reached an L4 surface (`EIP_DIRECT`, `NLB`, or the ALB directly) of an application that is supposed to be reachable only through CloudFront + WAF. A non-empty result usually means the origin is exposed: the Security Group of the ALB or instance is not restricted to the CloudFront origin-facing managed prefix list.

```sql theme={null}
SELECT client_ip, max(live_score) AS score,
       array_agg(DISTINCT surface) AS surfaces,
       count_if(surface = 'WAF')    AS via_waf,
       count_if(surface <> 'WAF' AND reached_backend) AS direct_hits
FROM ingress_scored
WHERE severity IN ('HIGH','CRITICAL')
GROUP BY client_ip
HAVING count(DISTINCT surface) > 1
   AND count_if(surface <> 'WAF' AND reached_backend) > 0
ORDER BY score DESC;
```

**Q4: WAF effectiveness gap.** These are Critical actors that the existing WebACL allowed:

```sql theme={null}
SELECT resource AS webacl, count(*) AS allowed_requests,
       count(DISTINCT client_ip) AS actors
FROM ingress_scored
WHERE surface = 'WAF' AND severity = 'CRITICAL' AND edge_action = 'ALLOW'
GROUP BY 1 ORDER BY 2 DESC;
```

For the top N actors in Q2–Q4, add context to the report with `GET /intel/{ipv4}` (reports, members, MITRE). This sends only the attacker IP to OneFirewall, never your log content.

***

## Method 3: AWS WAF / Network Firewall in shadow mode

Method 3 pushes the scored feed into native AWS enforcement objects with a **non-blocking** action. Every request from a scored IP is labelled and counted, and the WAF log records what the WebACL actually decided. The PoV metric is "requests from Critical/High actors that your current WebACL allowed". The production change is a single action flip.

### 3.1 HTTP surfaces: AWS WAF IP sets + COUNT rules

Create one IP set per severity band (REGIONAL scope for ALB / API Gateway, CLOUDFRONT scope in `us-east-1` for distributions):

```bash theme={null}
for band in critical high; do
  aws wafv2 create-ip-set --name ofa-$band --scope REGIONAL \
    --ip-address-version IPV4 --addresses '[]' --region eu-west-1
done
```

Add rules at the **lowest priority numbers** in each WebACL, so they are evaluated before any terminating rule. `Count` is non-terminating: evaluation continues, and the final decision of your existing rules is still logged.

```json theme={null}
{
  "Name": "ofa-critical",
  "Priority": 0,
  "Statement": { "IPSetReferenceStatement": { "ARN": "arn:aws:wafv2:eu-west-1:<acct>:regional/ipset/ofa-critical/<id>" } },
  "Action": { "Count": {} },
  "RuleLabels": [ { "Name": "ofa:critical" } ],
  "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "ofa-critical" }
}
```

Repeat with `ofa-high` / `ofa:high` at priority 1. Each IP-set reference rule costs 1 WCU.

> [!WARNING]
>
> Use `IPSetForwardedIPConfig` (`X-Forwarded-For`) **only** on a WebACL attached to an ALB whose Security Group accepts traffic from the CloudFront origin-facing prefix list only. Otherwise the header can be forged by the client. The preferred setup is to attach the OneFirewall rules to the CloudFront-scope WebACL, where `clientIp` is the real client.

### 3.2 IP set sync Lambda

AWS WAF IP sets hold at most 10,000 addresses each. The sync takes the scored CSV, buckets it by severity, caps each band at the highest-scored 10,000 entries, and updates the sets with optimistic locking.

```python ofa_waf_sync.py theme={null}
import os, csv, io, urllib.request, boto3

API = "https://app.onefirewall.com/api/v1"
SCOPE = os.environ.get("SCOPE", "REGIONAL")
SETS = {  # band -> (min, max_exclusive, ip_set_name, ip_set_id)
    "critical": (175, 1001, "ofa-critical", os.environ["IPSET_CRITICAL_ID"]),
    "high":     (120, 175,  "ofa-high",     os.environ["IPSET_HIGH_ID"]),
}
WAF_LIMIT = 10000
token = boto3.client("secretsmanager").get_secret_value(
    SecretId=os.environ["OFA_TOKEN_SECRET"])["SecretString"]
waf = boto3.client("wafv2")

def fetch():
    req = urllib.request.Request(f"{API}/flat/120?list=NO",
                                 headers={"Authorization": f"Bearer {token}"})
    with urllib.request.urlopen(req, timeout=120) as r:
        rows = list(csv.DictReader(io.StringIO(r.read().decode())))
    return [r for r in rows if not r.get("IS_CDN")]

def handler(event, context):
    rows = fetch()
    out = {}
    for band, (lo, hi, name, set_id) in SETS.items():
        sel = sorted((r for r in rows if lo <= int(r["LiveScore"]) < hi),
                     key=lambda r: -int(r["LiveScore"]))[:WAF_LIMIT]
        addrs = [f'{r["IPv4"]}/32' for r in sel]
        cur = waf.get_ip_set(Name=name, Scope=SCOPE, Id=set_id)
        waf.update_ip_set(Name=name, Scope=SCOPE, Id=set_id,
                          Addresses=addrs, LockToken=cur["LockToken"])
        out[band] = len(addrs)
    return out
```

Run it hourly. Execution role: `wafv2:GetIPSet` and `wafv2:UpdateIPSet` on the two IP set ARNs only, plus the secret. `UpdateIPSet` calls are recorded in CloudTrail, which is the change evidence for auditors.

### 3.3 Reading the result

Query the WAF logs (AWS `waf_logs` DDL) for labelled requests and the final action taken by your existing rules:

```sql theme={null}
SELECT
  regexp_extract(l.name, 'ofa:(critical|high)', 1) AS ofa_band,
  action                                          AS final_action,
  terminatingruleid,
  count(*)                                        AS requests,
  count(DISTINCT httprequest.clientip)            AS actors
FROM waf_logs
CROSS JOIN UNNEST(labels) AS t(l)
WHERE l.name LIKE '%:ofa:%'
GROUP BY 1, 2, 3
ORDER BY 1, requests DESC;
```

`final_action = ALLOW` rows are the gap that OneFirewall would close. Rows with `BLOCK` by a managed rule group show where the existing controls and the Alliance agree. To move to enforcement, change `"Count": {}` to `"Block": {}` for the band, following the threshold calibration in [Crime Score](https://docs.onefirewall.com/essentials/crime-score.md).

### 3.4 Non-HTTP surfaces: direct EIP and NLB

AWS WAF cannot be attached to an EC2 ENI or an NLB, and the native per-VPC primitives cannot hold a deny list of this size:

| Option | Can it hold a scored deny list? |
| - | - |
| Security Groups | No. Allow rules only. |
| Network ACLs | Not at this scale. 20 rules per direction by default (hard maximum 40). |
| AWS Network Firewall (stateful, Suricata-compatible) | Yes. Use an IP set variable or a referenced managed prefix list with `alert` rules for shadow mode and `drop` for enforcement. Requires Network Firewall endpoints in the ingress path (IGW edge route table association). |
| Gateway Load Balancer + third-party NGFW | Yes, through the vendor's OneFirewall integration (e.g. [FortiGate](https://docs.onefirewall.com/wcf-agents/fortigate.md), [Palo Alto](https://docs.onefirewall.com/wcf-agents/paloalto.md), [Check Point](https://docs.onefirewall.com/wcf-agents/checkpoint-feeds.md)). |

If Network Firewall is already deployed, add a stateful rule group in shadow mode:

```
alert ip $OFA_CRITICAL any -> $HOME_NET any (msg:"OneFirewall critical actor"; sid:9100001; rev:1;)
alert ip $OFA_HIGH     any -> $HOME_NET any (msg:"OneFirewall high actor";     sid:9100002; rev:1;)
```

Populate `$OFA_CRITICAL` / `$OFA_HIGH` with the same sync Lambda (`network-firewall:UpdateRuleGroup`, or `ec2:ModifyManagedPrefixList` if you use IP set references). Check the Network Firewall quotas for rule group capacity and IP set reference size before choosing the list size.

If Network Firewall is **not** in the ingress path, do not introduce it for a PoV. Direct EIP and NLB exposure is already fully measured by Method 1 or 2 from VPC Flow Logs, and enforcement can be designed after the readout.

***

## SOC 2 control mapping

| Concern | Implementation in this design | Trust Services Criteria |
| - | - | - |
| Least-privilege access to logs | Read-only `s3:GetObject`/`ListBucket` on named prefixes, `kms:Decrypt` constrained by `kms:ViaService` | CC6.1, CC6.3 |
| Third-party access | None in any method. Method 1 runs on a customer-owned host with a customer-owned read-only role. | CC6.1, CC6.2, CC9.2 |
| No inbound exposure of PoV tooling | Method 1 host and Method 2/3 Lambdas need egress only. No inbound rules. | CC6.6 |
| Egress restricted to the vendor endpoint | Proxy or Network Firewall domain allow-list: `app.onefirewall.com:443` | CC6.6, CC6.7 |
| Data residency / confidentiality | Logs never leave the account. Only authenticated GETs (and, optionally, per-IP `/intel` lookups of attacker IPs) go to OneFirewall. | C1.1, CC6.7 |
| Encryption | SSE-KMS on the analysis bucket and on the Method 1 host disk (ALB log bucket SSE-S3 per AWS constraint), TLS 1.2+ to the API | CC6.1, CC6.7 |
| Change management | Method 1 script reviewed and approved through software intake (versioned, checksum-verified). All PoV resources in IaC (Terraform/CloudFormation), tagged `Project=ofa-pov`, raised through the normal change ticket. WAF rules start in `Count`. | CC8.1 |
| Audit trail | CloudTrail for `AssumeRole`, `UpdateIPSet`, S3 data events (records every object the Method 1 role read) on the analysis bucket | CC7.2 |
| API token handling | Secrets Manager, rotation on PoV close, scoped to the PoV organisation | CC6.1 |
| Disposal | S3 lifecycle expiry on `ofa-pov/` (e.g. 30 days), local log copies on the Method 1 host deleted at PoV close, token revoked | C1.2 |

***

## PoV runbook (10-day analysis window)

**1. Day -3 to 0: scoping**

Agree on the accounts/Regions and the list of internet-facing resources (ENI inventory), choose Method 1, 2 or 3 (or a combination), confirm that the log sources are enabled, raise the change ticket, and issue the OneFirewall API token (Method 2/3) and, for Method 1, obtain the script release and checksum from the OneFirewall team and pass it through software intake.

**2. Day 0: deploy**

Apply the IaC. Validate with `curl -s https://app.onefirewall.com/api/v1/version` from the analysis host / Lambda subnet, a first feed snapshot, and a first non-empty result (a Method 1 dry run over one day, or the `ingress_events` query for Method 2).

**3. Day 1–10: collect**

Daily: feed snapshot, ENI inventory refresh, sanity check of Q1 (Method 2). Method 1: run the script once at the end of the window, using the daily snapshots. Method 3: hourly IP set sync. Nothing is blocked.

**4. Day 11: readout**

Deliverables: the Method 1 PDF report and/or per-surface/per-severity summary (Q1), CSV of allowed malicious actors with score, severity, ASN, surfaces and backend reach (Q2), origin-bypass findings (Q3), WAF gap (Q4 / 3.3), `/intel` context for the top actors, and an enforcement plan per surface with a starting threshold.

**5. Close**

Revoke the token, delete the local log copies and the read-only role if it was created for the PoV, let lifecycle rules expire the PoV data or retain it as audit evidence, and remove the WAF COUNT rules or keep them as the pre-production baseline.

> [card] [Standard PoV](https://docs.onefirewall.com/essentials/pov.md)
>
> On-prem/private cloud PoV with syslog ingestion.

> [card] [S3 Log Processing](https://docs.onefirewall.com/essentials/logs-events/s3-log-processing.md)
>
> Authentication patterns for the AWS OFA Log Adapter.

> [card] [Crime Score](https://docs.onefirewall.com/essentials/crime-score.md)
>
> Score model and enforcement thresholds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.