API Firewall

• In the Azure Portal, choose Create a resource and search the Marketplace for Wallarm API Firewall on Ubuntu 24.04 LTS by SecureAnyCloud

• Select the offer and choose Create

• Choose your subscription, resource group and region

• Set the VM size to Standard_B2s

• Leave the administrator username as azureuser and upload or generate your SSH public key

• Under Inbound port rules, allow SSH (22) and HTTP (80)

• On the Disks tab, choose Standard SSD for the OS disk

• Select Review and create, then Create

Under Networking, restrict ports 22 and 80 to your own address ranges. An HTTP Basic gate protects the console, but there is no reason to expose it to the whole internet.

az vm image terms accept --urn sac1647283583153:api-firewall-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-resource-group \
  --name api-firewall-01 \
  --image sac1647283583153:api-firewall-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --storage-sku StandardSSD_LRS \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
# Then open the console port, scoped to the ranges you control
az vm open-port --resource-group my-resource-group --name api-firewall-01 --port 80 --priority 900

# If you do not have the address to hand, ask Azure for it first:
az vm show --resource-group my-resource-group --name api-firewall-01 -d --query publicIps -o tsv ssh azureuser@<vm-ip>

Four units make up the appliance. All four should report active.

for U in api-firewall.service sac-demo-api.service nginx.service api-firewall-firstboot.service; do printf '%-34s %s\n' "$U" "$(systemctl is-active $U)" done

Expected output:

api-firewall.service active sac-demo-api.service active nginx.service active api-firewall-firstboot.service active

api-firewall-firstboot.service is a one-shot unit that runs once, on the first boot of this VM. Afterwards it reports active (exited), which shows that it completed rather than never ran.

Ask the firewall itself what it is:

curl -s --max-time 5 http://127.0.0.1:9667/v1/liveness

Expected output:

{"status":"up","build":"0.9.6","host":"api-firewall-01"}

Only ports 22 and 80 are reachable from outside the VM. The firewall, its health API and the demo upstream are all bound to loopback, so the front door is the only way in:

ss -lntH | awk '{print $4}' | sort

Nothing is baked into the image. API Firewall ships no accounts. The one credential that this appliance uses is the HTTP Basic gate in front of the console and the protected API. The first boot generated it on this virtual machine, and it exists nowhere else.

sudo cat /root/api-firewall-credentials.txt

The file is 0600 root:root, so only root can read it. It contains these keys:

Key Meaning

APIFW_CONSOLE_USERNAME The HTTP Basic username, always apifw

APIFW_CONSOLE_PASSWORD A 32 character password generated on this VM

APIFW_CONSOLE_URL The appliance console

APIFW_LIVENESS_URL The firewall liveness probe, as JSON

APIFW_READINESS_URL The firewall readiness probe, as JSON

APIFW_SPEC_URL The specification currently being enforced

First boot requests every URL in that file, and each must answer 200 before the boot can complete. The appliance therefore never hands you a link that it does not serve.

Before you open anything, confirm that the gate works. Every route refuses an anonymous caller:

for R in / /openapi.yaml /v1/products /firewall/liveness; do printf ' %-22s HTTP %s\n' "$R" \
  "$(curl -s -o /dev/null -w '%{http_code}' --max-time 8 http://127.0.0.1$R)" done

Expected output:

/ HTTP 401 /openapi.yaml HTTP 401 /v1/products HTTP 401 /firewall/liveness HTTP 401

Every credential that an attacker would try first is refused too:

for D in admin:admin admin:password apifw:apifw wallarm:wallarm root:root guest:guest; do printf ' %-22s HTTP %s\n' "$D" \
  "$(curl -s -o /dev/null -w '%{http_code}' --max-time 8 -u $D http://127.0.0.1/)" done

This is by design. During first boot, the appliance starts a throwaway loopback-only listener that uses this VM's real credential file. It proves against that listener that an unauthenticated request is answered with exactly 401, and only then writes the marker that permits nginx to start. If the proof fails, port 80 is never opened.

There is exactly one deliberate exception: a two-byte liveness probe for a load balancer, which reveals nothing:

curl -s -o /dev/null -w 'nginx-health: HTTP %{http_code}\n' http://127.0.0.1/nginx-health

Browse to your VM over HTTP and sign in with the username and password from Step 5.

http://<vm-ip>/

The console reads the status cards from the running process and the live configuration file, not from hard-coded values. They always describe what the firewall is enforcing right now.

Choose Run all scenarios. Each scenario sends a real HTTP request through the firewall on this VM and shows exactly what came back.

The firewall proxies a request that the specification describes to the upstream, and validates the response on the way back:

A request that the specification does not describe never reaches the upstream:

To do the same from the command line, use the credentials from Step 5:

U=$(sudo grep '^APIFW_CONSOLE_USERNAME=' /root/api-firewall-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^APIFW_CONSOLE_PASSWORD=' /root/api-firewall-credentials.txt | cut -d= -f2-)
echo "ALLOWED conforming GET : HTTP $(curl -s -o /dev/null -w '%{http_code}' -u "$U:$P" 'http://127.0.0.1/v1/products?limit=3')"
echo "BLOCKED wrong type : HTTP $(curl -s -o /dev/null -w '%{http_code}' -u "$U:$P" 'http://127.0.0.1/v1/products?limit=not-an-integer')"
echo "BLOCKED over the maximum : HTTP $(curl -s -o /dev/null -w '%{http_code}' -u "$U:$P" 'http://127.0.0.1/v1/products?limit=9999')"
echo "BLOCKED shadow endpoint : HTTP $(curl -s -o /dev/null -w '%{http_code}' -u "$U:$P" http://127.0.0.1/v1/leak)"
echo "BLOCKED bad response : HTTP $(curl -s -o /dev/null -w '%{http_code}' -u "$U:$P" http://127.0.0.1/v1/products/0)"

Expected output:

ALLOWED conforming GET : HTTP 200 BLOCKED wrong type : HTTP 403 BLOCKED over the maximum : HTTP 403 BLOCKED shadow endpoint : HTTP 403 BLOCKED bad response : HTTP 403

When the firewall refuses a request, it gives the reason in a response header:

U=$(sudo grep '^APIFW_CONSOLE_USERNAME=' /root/api-firewall-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^APIFW_CONSOLE_PASSWORD=' /root/api-firewall-credentials.txt | cut -d= -f2-)
curl -s -D - -o /dev/null -u "$U:$P" 'http://127.0.0.1/v1/products?limit=not-an-integer' \
  | tr -d '\r' | grep -iE '^(HTTP/|Apifw-Validation-Status)'

Expected output:

HTTP/1.1 403 Forbidden Apifw-Validation-Status: request-parameter:unknown:limit

The five things that got blocked, and why

Request Why it was refused

GET /v1/products?limit=not-an-integer The specification types limit as an integer

GET /v1/products?limit=9999 The specification caps limit at 50

POST /v1/orders with {"productId":"one","quantity":0} Wrong type, below the declared minimum, and a required field missing

GET /v1/leak A shadow endpoint: it exists on the upstream but is not in the specification

GET /v1/products/0 Response validation: the upstream answered 200 with a price of "not-a-number" where the schema requires a number

The last two deserve a closer look. /v1/leak does exist on the demo upstream and does return data. The firewall refuses it only because the specification does not declare it. For /v1/products/0, the upstream is the component that misbehaves, and the firewall stops the malformed payload before the client sees it.

The console renders the enforced contract directly from the file that the firewall loaded:

You can read the same contract from the shell:

U=$(sudo grep '^APIFW_CONSOLE_USERNAME=' /root/api-firewall-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^APIFW_CONSOLE_PASSWORD=' /root/api-firewall-credentials.txt | cut -d= -f2-)
curl -s -u "$U:$P" http://127.0.0.1/openapi.json | jq -r '.paths | keys[]'

Expected output:

/v1/orders /v1/products /v1/products/{productId} /v1/status

Anything not in that list is a shadow endpoint, and the firewall rejects it before it reaches the upstream.

This is the step that the appliance exists for. Two things change: the specification and the upstream.

Copy your own OpenAPI 3.0 document into place, point the firewall at your service, and restart. Replace <your-domain> with the host that your API listens on.

# 1. Your own specification becomes the contract the firewall enforces
sudo cp /path/to/my-openapi.yaml /etc/api-firewall/openapi.yaml
sudo chown root:apifw /etc/api-firewall/openapi.yaml
sudo chmod 0640 /etc/api-firewall/openapi.yaml
# 2. Point the firewall at your service
sudo sed -i 's|^APIFW_SERVER_URL=.*|APIFW_SERVER_URL=http://<your-domain>:3000|' \
  /etc/api-firewall/api-firewall.env
# 3. Restart, and republish the console's view so it describes the new contract sudo systemctl restart api-firewall.service sudo /usr/local/sbin/api-firewall-publish-config.sh # 4. Once your own API is behind the firewall, retire the demo upstream sudo systemctl disable --now sac-demo-api.service

The firewall refuses to start on an invalid configuration. A missing specification, an unparseable specification, an empty upstream or an invalid validation mode fails the preflight check. systemd then reports the start as failed instead of bringing up an appliance that would silently allow everything through. Check the outcome:

systemctl is-active api-firewall.service

A note on your specification. The quality of the protection is the quality of your OpenAPI document. A field typed as a bare string with no constraints allows any string. Declare types, formats, minimums, maximums, required arrays and additionalProperties: false where you can. Describe your response schemas as well as your requests, because response schemas turn the response validator on.

If you switch straight to BLOCK in front of a live API whose specification may be incomplete, the firewall rejects real traffic. API Firewall has a monitoring mode for this situation.

sudo sed -i 's|^APIFW_REQUEST_VALIDATION=.*|APIFW_REQUEST_VALIDATION=LOG_ONLY|' /etc/api-firewall/api-firewall.env
sudo sed -i 's|^APIFW_RESPONSE_VALIDATION=.*|APIFW_RESPONSE_VALIDATION=LOG_ONLY|' /etc/api-firewall/api-firewall.env
sudo systemctl restart api-firewall.service for i in $(seq 1 20); do curl -sf -o /dev/null --max-time 3 http://127.0.0.1:9667/v1/liveness && break; sleep 1; done grep -E '^APIFW_(REQUEST|RESPONSE)_VALIDATION=' /etc/api-firewall/api-firewall.env

Expected output:

APIFW_REQUEST_VALIDATION=LOG_ONLY APIFW_RESPONSE_VALIDATION=LOG_ONLY

When you are satisfied that your specification is complete, switch both settings back:

sudo sed -i 's|^APIFW_REQUEST_VALIDATION=.*|APIFW_REQUEST_VALIDATION=BLOCK|' /etc/api-firewall/api-firewall.env
sudo sed -i 's|^APIFW_RESPONSE_VALIDATION=.*|APIFW_RESPONSE_VALIDATION=BLOCK|' /etc/api-firewall/api-firewall.env
sudo systemctl restart api-firewall.service for i in $(seq 1 20); do curl -sf -o /dev/null --max-time 3 http://127.0.0.1:9667/v1/liveness && break; sleep 1; done grep -E '^APIFW_(REQUEST|RESPONSE)_VALIDATION=' /etc/api-firewall/api-firewall.env

In LOG_ONLY, the firewall refuses nothing. It writes every request that would have been blocked to the log with the rule it broke, and reports undocumented endpoints that answer requests as shadow APIs. Run production traffic through the firewall, read the log and fix the gaps in your specification. Then switch both settings back to BLOCK.

The three modes are:

Mode Behaviour

BLOCK Refuse anything that does not match, with the configured status code. The shipped default

LOG_ONLY Allow everything, record what would have been refused

DISABLE Turn that direction of validation off entirely

In proxy mode, the firewall's observability is its structured JSON log. The log records every block with a request id, the path, the method and the exact rule that rejected the request.

sudo journalctl -u api-firewall.service --no-pager -n 400 -o cat 2>/dev/null \
  | grep 'request blocked' | tail -5 \
  | jq -r '"blocked \(.method) \(.path) request_id=\(.request_id)"' || true

Expected output:

blocked GET /v1/products request_id=a614d8e5-c915-48d6-8680-a952e07823f4 blocked POST /v1/orders request_id=1c0f77a2-7bd2-4a05-9a1e-2c0a0b7a3f11

Each of those is one line of JSON in the journal. In full, a single block looks like this, and it names the exact schema rule that rejected the request:

{"level":"error","error":"parameter \"limit\" in query has an error: value not-an-integer: an invalid integer: invalid syntax","request_id":"a614d8e5-...","host":"127.0.0.1", "path":"/v1/products","method":"GET","message":"Request validation error: request blocked"}

To follow the log live while you test, run this command in a second terminal and leave it running:

sudo journalctl -u api-firewall.service -f -o cat

The liveness and readiness probes return JSON and suit a load balancer or an uptime monitor. Readiness reflects whether the connection pool to your upstream is healthy, so it becomes unhealthy when your backend does:

U=$(sudo grep '^APIFW_CONSOLE_USERNAME=' /root/api-firewall-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^APIFW_CONSOLE_PASSWORD=' /root/api-firewall-credentials.txt | cut -d= -f2-)
curl -s -u "$U:$P" http://127.0.0.1/firewall/readiness

By default, the firewall listens on 127.0.0.1:8282 and nginx on port 80 is the only public entrance. This gives you one place to terminate TLS, one place to gate access and one access log. If you want clients to connect to the firewall directly, change its listener and open the port.

# After this, clients speak to http://<vm-ip>:8282/ instead of going through nginx
sudo sed -i 's|^APIFW_URL=.*|APIFW_URL=http://0.0.0.0:8282/|' /etc/api-firewall/api-firewall.env
sudo systemctl restart api-firewall.service

Then allow inbound TCP 8282 in your network security group, scoped to the clients that need it. The firewall performs no authentication. It validates shape, not identity, so if you expose it directly, authentication is your API's responsibility.