Cloudflare Web Application Firewall downloader

Build Status

A library, CLI, and docker image that downloads Cloudflare WAF logs for a specified zone and time range.

Schema

See src/waf_logs/resources/db/ for a list of schemas that are auto-applied at start. This can be disabled by passing --ensure_schema False.

Quickstart

The project is published at https://pypi.org/project/waf-downloader/.

Install it via:

pip install waf-downloader

# or alternatively, directly from git
pip install "git+https://github.com/MihaiBojin/waf-downloader@main"

Or with Docker:

docker pull docker.io/mihaibojin/waf-downloader:latest

The list of published images can be found at: https://github.com/MihaiBojin/waf-downloader/pkgs/container/waf-downloader

and

https://hub.docker.com/repository/docker/mihaibojin/waf-downloader/tags

Build and run with Docker

Define secrets in an .env file (do not quote values):

CLOUDFLARE_TOKEN=...
DB_CONN_STR=...

The Cloudflare token is required (see required permissions), but the connection string is optional. If skipped, it will result in logs being printed to stdout.

IMPORTANT: This project uses taskfile.dev, which you will need to install for running the following commands:

# Build
task docker-build

# Load all logs in zone, starting 5 minutes prior
task docker-run -- --zone_id $CLOUDFLARE_ZONE_ID --start_minutes_ago 5

# And alternatively, only output the logs
task docker-run -- --zone_id $CLOUDFLARE_ZONE_ID --start_minutes_ago 5 2>/dev/null

# Do not specify a start time, relying on a starting timestamp stored in the database
# If a timestamp is not found in the database, or specified with --start_minutes_ago, the downloader will start 5 minutes prior
# This functionality makes it easy to run waf-downloader as a cron job
# NOTE: specifying --start_minutes_ago will always override the timestamp stored in the database, causing potential gaps in the data
task docker-run -- --zone_id $CLOUDFLARE_ZONE_ID

Publishing to PyPI

GitHub-based version publishing

The simplest way to publish a new version (if you have committer rights) is to tag a commit and push it to the repo:

# At a certain commit, ideally after merging a PR to main
git tag v0.1.x
git push origin v0.1.x

A GitHub Action will run, build the library and publish it to the PyPI repositories.

Manual publish

These steps can also be performed locally. For these commands to work, you will need to export two environment variables (or define them in .env):

export TESTPYPI_PASSWORD=... # token for https://test.pypi.org/legacy/
export PYPI_PASSWORD=... # token for https://upload.pypi.org/legacy/

First, publish to the test repo and inspect the package:

task publish-test

If correct, distribute the wheel to the PyPI index:

task publish

Verify the distributed code

task publish-verify

Cloudflare WAF documentation

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

waf_downloader-0.1.19.tar.gz (22.9 kB view details)

Uploaded Oct 17, 2024 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

waf_downloader-0.1.19-py3-none-any.whl (20.7 kB view details)

Uploaded Oct 17, 2024 Python 3

File details

Details for the file waf_downloader-0.1.19.tar.gz.

File metadata

Download URL: waf_downloader-0.1.19.tar.gz
Upload date: Oct 17, 2024
Size: 22.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/5.1.1 CPython/3.13.0

File hashes

Hashes for waf_downloader-0.1.19.tar.gz
Algorithm	Hash digest
SHA256	`092d4a663d185d9e5ae9cede2c38754c5a5c95d67995922e19f738c39deb9e9e`
MD5	`180163aa69b68313b3737314cf2e4adb`
BLAKE2b-256	`bb3a4c7fe6bed6924bbeef568cfc8fd8320ceb50e55b607a26e30ebcb7dca147`

See more details on using hashes here.

File details

Details for the file waf_downloader-0.1.19-py3-none-any.whl.

File metadata

Download URL: waf_downloader-0.1.19-py3-none-any.whl
Upload date: Oct 17, 2024
Size: 20.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/5.1.1 CPython/3.13.0

File hashes

Hashes for waf_downloader-0.1.19-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d0c0735467ee4805c11a0b41f41b9f16276442ed2bb0d94b7048347b37f295e6`
MD5	`36855b131a3176265471f8a771e58815`
BLAKE2b-256	`1e38461634ef29907ca757512259273da916c81e9d322b58d88ad978c98dc0c5`