Getting Started

This page takes you from nothing to a blocked request in about ten minutes. You will write one small configuration file, check it, run the router, and send it a test attack.

Status

vigilant-heron is in early development. Run every new site in shadow mode first, and read the log before you enforce anything.

1. Install

Build the router from source, or build its Docker image, as the Installation page shows. The steps below assume the vigilant-heron command is on your PATH. With Docker, run the same commands inside the container, as the Installation page shows.

2. Start a test upstream

The router forwards allowed requests to an upstream, which is your application. To try the router without an application, serve a folder with Python's built-in web server. Run this in its own terminal:

mkdir -p site && echo "hello from the upstream" > site/index.html
python3 -m http.server 3000 --bind 127.0.0.1 --directory site

3. Write a minimal configuration

Save this as vigilant-heron.conf. It listens on port 8080 and forwards requests for example.com to an app on port 3000.

listen 127.0.0.1:8080;              # the address the router listens on
pid vigilant-heron.pid;             # where the router writes its process id

decision {
    backend jev;                    # the decision model; it reads its key from TYPESAFE_API_KEY
}

site example.com {
    upstream http://127.0.0.1:3000; # where allowed requests go
    mode shadow;                    # record decisions, block nothing
}

• pid is a relative path, so it is resolved from the directory you run the command in. This guide runs every command from the directory that holds vigilant-heron.conf, so the pid file is written there.
• upstream is your application. Here it is the test server from step 2.
• mode shadow means the router forwards every request and only records what it would have blocked.

4. Check the file

-t reads the file, validates it, and exits. It does not start the server.

$ TYPESAFE_API_KEY=... vigilant-heron -t -c vigilant-heron.conf
configuration file vigilant-heron.conf test is successful

A mistake prints the file and line, for example vigilant-heron.conf:6: unknown directive "upstrem", and exits 1. Fix the line and run the check again.

5. Run the router

TYPESAFE_API_KEY=... vigilant-heron -c vigilant-heron.conf

The router keeps running in the foreground. Leave it in its own terminal. It prints one JSON line for each request.

6. Send a normal request and a test attack

In a second terminal, send an ordinary request. It goes through the router to the test upstream:

curl -i http://127.0.0.1:8080/ -H "Host: example.com"

The answer is 200 OK with hello from the upstream.

Now send a request whose query string contains a SQL injection:

curl -i "http://127.0.0.1:8080/?id=1%20UNION%20SELECT%20password%20FROM%20users" \
  -H "Host: example.com"

Shadow mode forwards this request too, so the answer is still 200 OK. The router records what it would have done. Look at the router's terminal. The log line for the attack contains these fields, among others:

{"status":"200","action":"allow","reason":"rule","rule_id":"vh-sqli-001","would_have":"block",...}

• rule_id is the built-in rule that matched. vh-sqli-001 matches UNION SELECT in a query string.
• would_have is block. In enforce mode, the router would have answered with 403.
• action is allow, because shadow mode forwarded the request.

7. Switch to enforce mode

When the shadow log shows the blocks you expect, change mode shadow; to mode enforce; in the file. Then reload the configuration with the -s command. This sends the router a signal, so it reads the file again without a restart:

vigilant-heron -s reload -c vigilant-heron.conf

Send the test attack again:

curl -i "http://127.0.0.1:8080/?id=1%20UNION%20SELECT%20password%20FROM%20users" \
  -H "Host: example.com"

The response is now 403 Forbidden, and the upstream never sees the request. The normal request from step 6 still returns 200 OK.

Next steps

• Installation covers Docker Compose, nginx and Cloudflare in front, and updates.
• Command line lists every option, including -T and the signal words for -s.
• How it works explains the order in which the router judges a request.
• Configuration lists every directive with its default.
• Decision backends covers the choice of model and the thresholds.
• Troubleshooting helps when a request is blocked, or when the router does not start.