{"owner":"bunkerity","repo":"bunkerweb","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n\nSource lives in `src/`: `api/` (FastAPI service), `ui/` (admin UI), `linux/` (distribution packages and service units), `bw/` and `common/` (core WAF logic), plus packaging targets like `all-in-one/` and other platform bundles. Integration assets and manifests are under `examples/`, while reusable configuration templates live in `env/`. MkDocs content for docs.bunkerweb.io sits in `docs/`. System tests, fixtures, and helper scripts are consolidated in `tests/`.\n\n## Build, Test, and Development Commands\n\nBootstrap Python deps per component, e.g. `pip install -r src/api/requirements.txt` or `pip install -r src/ui/requirements.txt`. Build a full appliance image with `docker build -f src/all-in-one/Dockerfile .`. Exercise integrations locally via `python tests/main.py docker`; swap `docker` for `linux`, `autoconf`, `swarm`, or `kubernetes` as needed (set the matching `TEST_DOMAIN*` env vars first). Regenerate docs with `mkdocs serve --watch` from the repo root. Run `pre-commit run --all-files` before pushing to execute the standard formatters and linters.\n\n## Coding Style & Naming Conventions\n\nPython uses Black (160 char lines) and Flake8 with ignores defined in `.pre-commit-config.yaml`; prefer snake_case for modules and functions, PascalCase for classes. Lua code is formatted with StyLua (see `stylua.toml`) and linted with Luacheck; follow lowercase module names and descriptive function names. Shell scripts must pass ShellCheck and stay POSIX-compatible unless a `#!/bin/bash` shebang is explicit. Front-end assets follow Prettier defaults.\n\n## Testing Guidelines\n\nHigh-level acceptance suites live in `tests/` and orchestrate Dockerized environments—verify Docker access and required `TEST_DOMAIN*` env vars before running. Add scenario files under `examples/<use-case>/tests.json` with descriptive names; tests should assert observable behavior rather than internals. For unit-style Python additions, provide lightweight checks inside the relevant module and hook them into integration flows when feasible. Capture regressions by replicating failing requests in the automated suites.\n\n## Commit & Pull Request Guidelines\n\nUse concise, present-tense messages; the history favors Conventional Commits (`feat:`, `fix:`, `docs:`) or `<component> - …` prefixes. Reference issue IDs when closing or relating tickets. Each PR should include a summary of changes, validation steps (commands or screenshots for UI changes), and updated docs or config when behavior shifts. Coordinate breaking changes with maintainers and flag them clearly in both commit body and PR description.\n\n## Security & Configuration Tips\n\nNever commit secrets—use sample files in `env/` or add new templates when introducing config. Review `.gitleaksignore` before adjusting dependencies. Docker Scout is used for container image vulnerability scanning in CI/CD—check the `container-build.yml` workflow for current scan configuration. When touching TLS, keys, or rule bundles, document rotation steps and default hardening in the accompanying docs update.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nBunkerWeb is an open-source Web Application Firewall (WAF) built on NGINX with a modular plugin architecture. It provides \"security by default\" for web services through multiple integration modes (Docker, Kubernetes, Swarm, Linux) and is fully configurable via environment variables.\n\n## Architecture\n\n### Core Components\n\n- **BunkerWeb Core** (`src/bw/`, `src/common/core/`): NGINX-based reverse proxy with security modules in Lua (request-time) and Python (jobs). Entry point: `src/bw/lua/bunkerweb.lua`.\n- **Scheduler** (`src/scheduler/`): Central orchestrator (\"brain\"). `main.py` runs the main loop; `JobScheduler.py` manages job execution with thread pools. Uses Python's `schedule` library.\n- **Autoconf** (`src/autoconf/`): Listens for Docker/Swarm/Kubernetes events and dynamically reconfigures BunkerWeb.\n- **API** (`src/api/`): FastAPI service with router-based architecture (`src/api/app/routers/` — auth, instances, services, configs, plugins, jobs). IP whitelist and rate limiting support.\n- **Web UI** (`src/ui/`): Flask app using Blueprints for routing (`src/ui/app/routes/` — configs, plugins, jobs, logs, instances, profile, etc.). Uses Flask-Login for auth and Jinja2 templates. `dependencies.py` is the central dependency injection point providing DB, DATA, BW_CONFIG, BW_INSTANCES_UTILS.\n- **Database** (`src/common/db/`): SQLAlchemy ORM with `model.py` defining all tables (Plugins, Settings, Services, Jobs, Custom_configs, Users, etc.). `Database.py` wraps high-level query methods. Supports SQLite (WAL mode), MariaDB, MySQL, PostgreSQL with QueuePool for connection pooling.\n\n### Configuration Flow\n\n1. Settings defined as environment variables (e.g., `USE_ANTIBOT=captcha`, `AUTO_LETS_ENCRYPT=yes`)\n2. Scheduler reads settings from environment or database\n3. **Configurator** (`src/common/gen/Configurator.py`) validates settings against `plugin.json` schemas with pre-compiled regex caches\n4. **Templator** (`src/common/gen/Templator.py`) renders NGINX configs from Jinja2 templates (`src/common/confs/`) using ProcessPoolExecutor for parallel rendering\n5. BunkerWeb instances reload with new configuration\n6. In multisite mode, prefix settings with server name: `www.example.com_USE_ANTIBOT=captcha`\n7. Multiple settings use numeric suffixes: `REVERSE_PROXY_URL_1=/api`, `REVERSE_PROXY_HOST_1=http://backend1`\n\n### Plugin System\n\nEach core module in `src/common/core/*/` contains:\n\n- `plugin.json`: Metadata with settings schema (id, name, version, stream, settings with context/type/regex/default, jobs array with schedule/reload/async flags)\n- `jobs/` folder: Python scripts for periodic tasks (e.g., downloading blocklists). Jobs specify `every` (once/minute/hour/day/week) and `reload` flag.\n- Lua code for request-time processing\n- `confs/` folder: NGINX configuration templates\n\nExternal plugins follow the same structure.\n\n### Lua Request Processing Pipeline\n\nThe Lua runtime (`src/bw/lua/`) processes requests through plugin hooks at NGINX phases: access, header_filter, body_filter, log. Key files:\n\n- `plugin.lua`: Plugin loader and execution across phases\n- `ctx.lua`: Per-request context management\n- `datastore.lua`: Shared data persistence (shared dict backed)\n- `cachestore.lua`: Request-level caching\n- `clusterstore.lua`: Cluster-aware storage (Redis)\n\n### Core Plugins (src/common/core/)\n\n42 plugins organized by function:\n\n- **Auth**: antibot (CAPTCHA), authbasic, mtls, crowdsec\n- **Threat Detection**: modsecurity (OWASP WAF), badbehavior, dnsbl, reversescan\n- **Access Control**: whitelist, blacklist, greylist, country, limit (rate limiting)\n- **SSL/TLS**: ssl, letsencrypt, customcert, selfsigned\n- **Proxy & Routing**: reverseproxy, realip, redirect, grpc, php\n- **Performance**: gzip, brotli, clientcache, redis\n- **Headers & Content**: headers, cors, inject, robotstxt, securitytxt\n- **Management**: sessions, metrics, backup, templates, bunkernet, ui, db, jobs\n\n### Shared Utilities (src/common/utils/)\n\n- `common_utils.py`: Docker secrets handling, hashing, version info, integration detection\n- `logger.py`: Logging with syslog support\n- `jobs.py`: Job helpers (atomic writes, file hashing, tar operations)\n- `ApiCaller.py`: HTTP client for inter-component API calls\n\n## Development Commands\n\n### Setup\n\n```bash\npip install -r src/scheduler/requirements.txt\npip install -r src/ui/requirements.txt\npip install -r src/api/requirements.txt\npre-commit install\n```\n\n### Build\n\n```bash\n# Build Docker image (all-in-one)\ndocker build -f src/all-in-one/Dockerfile -t bunkerweb:dev .\n\n# Build specific component\ndocker build -f src/scheduler/Dockerfile -t bunkerweb-scheduler:dev .\ndocker build -f src/ui/Dockerfile -t bunkerweb-ui:dev .\n```\n\n### Linting & Formatting\n\n```bash\n# Run all pre-commit hooks\npre-commit run --all-files\n\n# Individual tools\nblack .                          # Python formatting (160 char lines)\nflake8 .                         # Python linting (ignores E266,E402,E501,E722,W503)\nstylua .                         # Lua formatting\nluacheck src/                    # Lua linting (--std min)\nshellcheck scripts/*.sh          # Shell script linting\nprettier --write \"**/*.{js,ts,css,html,json,yaml,md}\"  # Frontend formatting\ncodespell                        # Spell checking\nrefurb                           # Python refactoring suggestions (excludes tests/)\n```\n\n### Run Development Instance\n\n```bash\n# Full stack with UI + API (recommended)\ndocker compose -f misc/dev/docker-compose.ui.api.yml up -d\n```\n\nDev compose files in `misc/dev/`:\n\n- `docker-compose.ui.api.yml` — Full stack (UI + API + core + MariaDB) — **recommended**\n- `docker-compose.ui.yml` — UI only (no API)\n- `docker-compose.all-in-one.yml` — Single container with all components\n- `docker-compose.autoconf.yml` — Docker autoconf mode\n- `docker-compose.wizard.yml` — Setup wizard\n\nDev credentials: UI `admin`/`P@ssw0rd`, API `admin`/`P@ssw0rd`, DB `bunkerweb`/`secret`.\n\nThe dev compose mounts `src/ui/app/` and `src/api/app/` as read-only volumes, so UI and API code changes apply without rebuilding (restart the container to pick up changes).\n\n### Database Migrations\n\n```bash\n# Alembic migrations in src/common/db/alembic/\n# Separate version directories per DB type: mariadb_versions, mysql_versions, postgresql_versions, sqlite_versions\n# Migration scripts also in src/common/db/alembic/\n```\n\n## Key Files\n\n- `src/common/settings.json`: Master list of all core settings with validation rules\n- `src/common/db/model.py`: SQLAlchemy ORM models for all tables\n- `src/common/db/Database.py`: High-level database wrapper\n- `src/common/gen/Configurator.py`: Settings validation engine\n- `src/common/gen/Templator.py`: NGINX config renderer\n- `src/scheduler/main.py`: Scheduler entry point\n- `src/scheduler/JobScheduler.py`: Job execution orchestrator\n- `src/ui/main.py`: Web UI entry point\n- `src/ui/app/dependencies.py`: UI dependency injection (DB, DATA, BW_CONFIG)\n- `src/api/app/core.py`: API entry point (imports all routers)\n- `src/bw/lua/bunkerweb.lua`: Main Lua runtime initialization\n- `pyproject.toml`: Black config (160 char lines)\n- `.pre-commit-config.yaml`: All linting/formatting rules\n\n## Important Patterns\n\n### Settings Context\n\n- `global`: Applied to all servers (e.g., `WORKER_PROCESSES`, `LOG_LEVEL`)\n- `multisite`: Can be server-specific (prefix with `SERVER_NAME_`)\n\n### Security Modes\n\n- `detect`: Log threats without blocking\n- `block`: Actively block threats (default)\n\n### Integration Modes\n\nSet one of these to `yes`: `AUTOCONF_MODE`, `SWARM_MODE`, `KUBERNETES_MODE`\n\n### Testing\n\n```bash\npython3 tests/main.py docker              # Docker integration tests\npython3 tests/main.py autoconf            # Autoconf tests\npython3 tests/main.py swarm               # Swarm tests\npython3 tests/main.py kubernetes           # Kubernetes tests\npython3 tests/main.py linux debian         # Linux tests (with distro)\n```\n\n- Tests scan `examples/*/tests.json` for test scenarios (type: string/status, url, expected results)\n- Real Docker environments with actual HTTP requests — tests verify observable behavior, not internals\n\n## Key Conventions\n\n- Python: snake_case (modules/functions), PascalCase (classes), Black formatting at 160 chars\n- Lua: lowercase module names, descriptive function names, StyLua formatting\n- Shell: POSIX-compatible unless `#!/bin/bash` shebang, pass ShellCheck\n- Commit messages: Conventional Commits (`feat:`, `fix:`, `docs:`) or `<component> - ...` format\n- UI translations in `src/ui/app/static/locales/`\n\n## External Resources\n\n- Documentation: <https://docs.bunkerweb.io>\n- Official Plugins: <https://github.com/bunkerity/bunkerweb-plugins>\n- Web UI Demo: <https://demo-ui.bunkerweb.io>\n",".github/copilot-instructions.md":"# Copilot Instructions for BunkerWeb\n\n## Project Overview\n\n- **BunkerWeb** is a next-generation, open-source Web Application Firewall (WAF) built on top of NGINX, with a modular, plugin-based architecture.\n- Major components: core (security logic), scheduler (configuration and job orchestration), web UI (management), plugin system (feature extension), and integrations (Docker, Kubernetes, Swarm, Linux, Azure).\n- Configuration is driven by environment variables (settings), custom NGINX/ModSecurity configs, and a backend database (SQLite, MariaDB, MySQL, PostgreSQL).\n\n## Key Directories\n\n- `src/`: Main source code (core, scheduler, plugins, UI, integrations)\n- `docs/`: Documentation, guides, and assets\n- `examples/`: Real-world configuration and deployment examples\n- `tests/`: Test scripts and scenarios\n- `misc/`: Utilities, scripts, and ASCII art\n\n## Developer Workflows\n\n- **Build/Run**: See `docs/quickstart-guide.md` and `README.md` for integration-specific instructions (Linux, Docker, Kubernetes, etc.).\n- **Testing**: Use scripts in `tests/` (e.g., `main.py`, `AutoconfTest.py`, `SwarmTest.py`).\n- **Debugging**: Logs and job execution are managed by the scheduler; use the web UI for live monitoring and troubleshooting.\n- **Plugins**: Add new features by placing plugins in the appropriate directory and updating settings. See `docs/plugins.md` and the [bunkerweb-plugins repo](https://github.com/bunkerity/bunkerweb-plugins).\n\n## Project-Specific Conventions\n\n- **Settings**: All configuration is via environment variables (e.g., `USE_ANTIBOT=captcha`). In multisite mode, prefix with the server name (e.g., `www.example.com_USE_ANTIBOT=captcha`).\n- **Multiple values**: Use numbered suffixes for repeated settings (e.g., `REVERSE_PROXY_URL_1`, `REVERSE_PROXY_URL_2`).\n- **Custom configs**: Place NGINX/ModSecurity customizations in designated config files or via the web UI.\n- **Localization**: UI translations in `src/ui/app/static/locales/`.\n\n## Integration Patterns\n\n- **Scheduler** is the central orchestrator for config, jobs, and service communication.\n- **Autoconf** listens for environment events (Docker, Swarm, Kubernetes) and updates config in real time.\n- **Web UI** interacts with the scheduler/database for live management.\n- **Plugins** extend core via settings and hooks; see plugin README files for details.\n\n## Examples\n\n- See `examples/` for integration and configuration samples.\n- See `src/common/core/` for core security modules (each with its own README).\n\n## External Resources\n\n- [Documentation](https://docs.bunkerweb.io)\n- [Web UI Demo](https://demo-ui.bunkerweb.io)\n- [Plugins](https://github.com/bunkerity/bunkerweb-plugins)\n\n## Contributing\n\n- Follow the [CONTRIBUTING.md](../CONTRIBUTING.md) and [SECURITY.md](../SECURITY.md) guidelines.\n- Use the [web UI](https://docs.bunkerweb.io/web-ui/) for most configuration and debugging tasks.\n\n---\n\n**Tip:** For new features, follow the patterns in `src/common/core/` and `src/ui/`. For integrations, reference the relevant subdirectory in `examples/` and `docs/`.\n"},"files":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n\nSource lives in `src/`: `api/` (FastAPI service), `ui/` (admin UI), `linux/` (distribution packages and service units), `bw/` and `common/` (core WAF logic), plus packaging targets like `all-in-one/` and other platform bundles. Integration assets and manifests are under `examples/`, while reusable configuration templates live in `env/`. MkDocs content for docs.bunkerweb.io sits in `docs/`. System tests, fixtures, and helper scripts are consolidated in `tests/`.\n\n## Build, Test, and Development Commands\n\nBootstrap Python deps per component, e.g. `pip install -r src/api/requirements.txt` or `pip install -r src/ui/requirements.txt`. Build a full appliance image with `docker build -f src/all-in-one/Dockerfile .`. Exercise integrations locally via `python tests/main.py docker`; swap `docker` for `linux`, `autoconf`, `swarm`, or `kubernetes` as needed (set the matching `TEST_DOMAIN*` env vars first). Regenerate docs with `mkdocs serve --watch` from the repo root. Run `pre-commit run --all-files` before pushing to execute the standard formatters and linters.\n\n## Coding Style & Naming Conventions\n\nPython uses Black (160 char lines) and Flake8 with ignores defined in `.pre-commit-config.yaml`; prefer snake_case for modules and functions, PascalCase for classes. Lua code is formatted with StyLua (see `stylua.toml`) and linted with Luacheck; follow lowercase module names and descriptive function names. Shell scripts must pass ShellCheck and stay POSIX-compatible unless a `#!/bin/bash` shebang is explicit. Front-end assets follow Prettier defaults.\n\n## Testing Guidelines\n\nHigh-level acceptance suites live in `tests/` and orchestrate Dockerized environments—verify Docker access and required `TEST_DOMAIN*` env vars before running. Add scenario files under `examples/<use-case>/tests.json` with descriptive names; tests should assert observable behavior rather than internals. For unit-style Python additions, provide lightweight checks inside the relevant module and hook them into integration flows when feasible. Capture regressions by replicating failing requests in the automated suites.\n\n## Commit & Pull Request Guidelines\n\nUse concise, present-tense messages; the history favors Conventional Commits (`feat:`, `fix:`, `docs:`) or `<component> - …` prefixes. Reference issue IDs when closing or relating tickets. Each PR should include a summary of changes, validation steps (commands or screenshots for UI changes), and updated docs or config when behavior shifts. Coordinate breaking changes with maintainers and flag them clearly in both commit body and PR description.\n\n## Security & Configuration Tips\n\nNever commit secrets—use sample files in `env/` or add new templates when introducing config. Review `.gitleaksignore` before adjusting dependencies. Docker Scout is used for container image vulnerability scanning in CI/CD—check the `container-build.yml` workflow for current scan configuration. When touching TLS, keys, or rule bundles, document rotation steps and default hardening in the accompanying docs update.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nBunkerWeb is an open-source Web Application Firewall (WAF) built on NGINX with a modular plugin architecture. It provides \"security by default\" for web services through multiple integration modes (Docker, Kubernetes, Swarm, Linux) and is fully configurable via environment variables.\n\n## Architecture\n\n### Core Components\n\n- **BunkerWeb Core** (`src/bw/`, `src/common/core/`): NGINX-based reverse proxy with security modules in Lua (request-time) and Python (jobs). Entry point: `src/bw/lua/bunkerweb.lua`.\n- **Scheduler** (`src/scheduler/`): Central orchestrator (\"brain\"). `main.py` runs the main loop; `JobScheduler.py` manages job execution with thread pools. Uses Python's `schedule` library.\n- **Autoconf** (`src/autoconf/`): Listens for Docker/Swarm/Kubernetes events and dynamically reconfigures BunkerWeb.\n- **API** (`src/api/`): FastAPI service with router-based architecture (`src/api/app/routers/` — auth, instances, services, configs, plugins, jobs). IP whitelist and rate limiting support.\n- **Web UI** (`src/ui/`): Flask app using Blueprints for routing (`src/ui/app/routes/` — configs, plugins, jobs, logs, instances, profile, etc.). Uses Flask-Login for auth and Jinja2 templates. `dependencies.py` is the central dependency injection point providing DB, DATA, BW_CONFIG, BW_INSTANCES_UTILS.\n- **Database** (`src/common/db/`): SQLAlchemy ORM with `model.py` defining all tables (Plugins, Settings, Services, Jobs, Custom_configs, Users, etc.). `Database.py` wraps high-level query methods. Supports SQLite (WAL mode), MariaDB, MySQL, PostgreSQL with QueuePool for connection pooling.\n\n### Configuration Flow\n\n1. Settings defined as environment variables (e.g., `USE_ANTIBOT=captcha`, `AUTO_LETS_ENCRYPT=yes`)\n2. Scheduler reads settings from environment or database\n3. **Configurator** (`src/common/gen/Configurator.py`) validates settings against `plugin.json` schemas with pre-compiled regex caches\n4. **Templator** (`src/common/gen/Templator.py`) renders NGINX configs from Jinja2 templates (`src/common/confs/`) using ProcessPoolExecutor for parallel rendering\n5. BunkerWeb instances reload with new configuration\n6. In multisite mode, prefix settings with server name: `www.example.com_USE_ANTIBOT=captcha`\n7. Multiple settings use numeric suffixes: `REVERSE_PROXY_URL_1=/api`, `REVERSE_PROXY_HOST_1=http://backend1`\n\n### Plugin System\n\nEach core module in `src/common/core/*/` contains:\n\n- `plugin.json`: Metadata with settings schema (id, name, version, stream, settings with context/type/regex/default, jobs array with schedule/reload/async flags)\n- `jobs/` folder: Python scripts for periodic tasks (e.g., downloading blocklists). Jobs specify `every` (once/minute/hour/day/week) and `reload` flag.\n- Lua code for request-time processing\n- `confs/` folder: NGINX configuration templates\n\nExternal plugins follow the same structure.\n\n### Lua Request Processing Pipeline\n\nThe Lua runtime (`src/bw/lua/`) processes requests through plugin hooks at NGINX phases: access, header_filter, body_filter, log. Key files:\n\n- `plugin.lua`: Plugin loader and execution across phases\n- `ctx.lua`: Per-request context management\n- `datastore.lua`: Shared data persistence (shared dict backed)\n- `cachestore.lua`: Request-level caching\n- `clusterstore.lua`: Cluster-aware storage (Redis)\n\n### Core Plugins (src/common/core/)\n\n42 plugins organized by function:\n\n- **Auth**: antibot (CAPTCHA), authbasic, mtls, crowdsec\n- **Threat Detection**: modsecurity (OWASP WAF), badbehavior, dnsbl, reversescan\n- **Access Control**: whitelist, blacklist, greylist, country, limit (rate limiting)\n- **SSL/TLS**: ssl, letsencrypt, customcert, selfsigned\n- **Proxy & Routing**: reverseproxy, realip, redirect, grpc, php\n- **Performance**: gzip, brotli, clientcache, redis\n- **Headers & Content**: headers, cors, inject, robotstxt, securitytxt\n- **Management**: sessions, metrics, backup, templates, bunkernet, ui, db, jobs\n\n### Shared Utilities (src/common/utils/)\n\n- `common_utils.py`: Docker secrets handling, hashing, version info, integration detection\n- `logger.py`: Logging with syslog support\n- `jobs.py`: Job helpers (atomic writes, file hashing, tar operations)\n- `ApiCaller.py`: HTTP client for inter-component API calls\n\n## Development Commands\n\n### Setup\n\n```bash\npip install -r src/scheduler/requirements.txt\npip install -r src/ui/requirements.txt\npip install -r src/api/requirements.txt\npre-commit install\n```\n\n### Build\n\n```bash\n# Build Docker image (all-in-one)\ndocker build -f src/all-in-one/Dockerfile -t bunkerweb:dev .\n\n# Build specific component\ndocker build -f src/scheduler/Dockerfile -t bunkerweb-scheduler:dev .\ndocker build -f src/ui/Dockerfile -t bunkerweb-ui:dev .\n```\n\n### Linting & Formatting\n\n```bash\n# Run all pre-commit hooks\npre-commit run --all-files\n\n# Individual tools\nblack .                          # Python formatting (160 char lines)\nflake8 .                         # Python linting (ignores E266,E402,E501,E722,W503)\nstylua .                         # Lua formatting\nluacheck src/                    # Lua linting (--std min)\nshellcheck scripts/*.sh          # Shell script linting\nprettier --write \"**/*.{js,ts,css,html,json,yaml,md}\"  # Frontend formatting\ncodespell                        # Spell checking\nrefurb                           # Python refactoring suggestions (excludes tests/)\n```\n\n### Run Development Instance\n\n```bash\n# Full stack with UI + API (recommended)\ndocker compose -f misc/dev/docker-compose.ui.api.yml up -d\n```\n\nDev compose files in `misc/dev/`:\n\n- `docker-compose.ui.api.yml` — Full stack (UI + API + core + MariaDB) — **recommended**\n- `docker-compose.ui.yml` — UI only (no API)\n- `docker-compose.all-in-one.yml` — Single container with all components\n- `docker-compose.autoconf.yml` — Docker autoconf mode\n- `docker-compose.wizard.yml` — Setup wizard\n\nDev credentials: UI `admin`/`P@ssw0rd`, API `admin`/`P@ssw0rd`, DB `bunkerweb`/`secret`.\n\nThe dev compose mounts `src/ui/app/` and `src/api/app/` as read-only volumes, so UI and API code changes apply without rebuilding (restart the container to pick up changes).\n\n### Database Migrations\n\n```bash\n# Alembic migrations in src/common/db/alembic/\n# Separate version directories per DB type: mariadb_versions, mysql_versions, postgresql_versions, sqlite_versions\n# Migration scripts also in src/common/db/alembic/\n```\n\n## Key Files\n\n- `src/common/settings.json`: Master list of all core settings with validation rules\n- `src/common/db/model.py`: SQLAlchemy ORM models for all tables\n- `src/common/db/Database.py`: High-level database wrapper\n- `src/common/gen/Configurator.py`: Settings validation engine\n- `src/common/gen/Templator.py`: NGINX config renderer\n- `src/scheduler/main.py`: Scheduler entry point\n- `src/scheduler/JobScheduler.py`: Job execution orchestrator\n- `src/ui/main.py`: Web UI entry point\n- `src/ui/app/dependencies.py`: UI dependency injection (DB, DATA, BW_CONFIG)\n- `src/api/app/core.py`: API entry point (imports all routers)\n- `src/bw/lua/bunkerweb.lua`: Main Lua runtime initialization\n- `pyproject.toml`: Black config (160 char lines)\n- `.pre-commit-config.yaml`: All linting/formatting rules\n\n## Important Patterns\n\n### Settings Context\n\n- `global`: Applied to all servers (e.g., `WORKER_PROCESSES`, `LOG_LEVEL`)\n- `multisite`: Can be server-specific (prefix with `SERVER_NAME_`)\n\n### Security Modes\n\n- `detect`: Log threats without blocking\n- `block`: Actively block threats (default)\n\n### Integration Modes\n\nSet one of these to `yes`: `AUTOCONF_MODE`, `SWARM_MODE`, `KUBERNETES_MODE`\n\n### Testing\n\n```bash\npython3 tests/main.py docker              # Docker integration tests\npython3 tests/main.py autoconf            # Autoconf tests\npython3 tests/main.py swarm               # Swarm tests\npython3 tests/main.py kubernetes           # Kubernetes tests\npython3 tests/main.py linux debian         # Linux tests (with distro)\n```\n\n- Tests scan `examples/*/tests.json` for test scenarios (type: string/status, url, expected results)\n- Real Docker environments with actual HTTP requests — tests verify observable behavior, not internals\n\n## Key Conventions\n\n- Python: snake_case (modules/functions), PascalCase (classes), Black formatting at 160 chars\n- Lua: lowercase module names, descriptive function names, StyLua formatting\n- Shell: POSIX-compatible unless `#!/bin/bash` shebang, pass ShellCheck\n- Commit messages: Conventional Commits (`feat:`, `fix:`, `docs:`) or `<component> - ...` format\n- UI translations in `src/ui/app/static/locales/`\n\n## External Resources\n\n- Documentation: <https://docs.bunkerweb.io>\n- Official Plugins: <https://github.com/bunkerity/bunkerweb-plugins>\n- Web UI Demo: <https://demo-ui.bunkerweb.io>\n",".github/copilot-instructions.md":"# Copilot Instructions for BunkerWeb\n\n## Project Overview\n\n- **BunkerWeb** is a next-generation, open-source Web Application Firewall (WAF) built on top of NGINX, with a modular, plugin-based architecture.\n- Major components: core (security logic), scheduler (configuration and job orchestration), web UI (management), plugin system (feature extension), and integrations (Docker, Kubernetes, Swarm, Linux, Azure).\n- Configuration is driven by environment variables (settings), custom NGINX/ModSecurity configs, and a backend database (SQLite, MariaDB, MySQL, PostgreSQL).\n\n## Key Directories\n\n- `src/`: Main source code (core, scheduler, plugins, UI, integrations)\n- `docs/`: Documentation, guides, and assets\n- `examples/`: Real-world configuration and deployment examples\n- `tests/`: Test scripts and scenarios\n- `misc/`: Utilities, scripts, and ASCII art\n\n## Developer Workflows\n\n- **Build/Run**: See `docs/quickstart-guide.md` and `README.md` for integration-specific instructions (Linux, Docker, Kubernetes, etc.).\n- **Testing**: Use scripts in `tests/` (e.g., `main.py`, `AutoconfTest.py`, `SwarmTest.py`).\n- **Debugging**: Logs and job execution are managed by the scheduler; use the web UI for live monitoring and troubleshooting.\n- **Plugins**: Add new features by placing plugins in the appropriate directory and updating settings. See `docs/plugins.md` and the [bunkerweb-plugins repo](https://github.com/bunkerity/bunkerweb-plugins).\n\n## Project-Specific Conventions\n\n- **Settings**: All configuration is via environment variables (e.g., `USE_ANTIBOT=captcha`). In multisite mode, prefix with the server name (e.g., `www.example.com_USE_ANTIBOT=captcha`).\n- **Multiple values**: Use numbered suffixes for repeated settings (e.g., `REVERSE_PROXY_URL_1`, `REVERSE_PROXY_URL_2`).\n- **Custom configs**: Place NGINX/ModSecurity customizations in designated config files or via the web UI.\n- **Localization**: UI translations in `src/ui/app/static/locales/`.\n\n## Integration Patterns\n\n- **Scheduler** is the central orchestrator for config, jobs, and service communication.\n- **Autoconf** listens for environment events (Docker, Swarm, Kubernetes) and updates config in real time.\n- **Web UI** interacts with the scheduler/database for live management.\n- **Plugins** extend core via settings and hooks; see plugin README files for details.\n\n## Examples\n\n- See `examples/` for integration and configuration samples.\n- See `src/common/core/` for core security modules (each with its own README).\n\n## External Resources\n\n- [Documentation](https://docs.bunkerweb.io)\n- [Web UI Demo](https://demo-ui.bunkerweb.io)\n- [Plugins](https://github.com/bunkerity/bunkerweb-plugins)\n\n## Contributing\n\n- Follow the [CONTRIBUTING.md](../CONTRIBUTING.md) and [SECURITY.md](../SECURITY.md) guidelines.\n- Use the [web UI](https://docs.bunkerweb.io/web-ui/) for most configuration and debugging tasks.\n\n---\n\n**Tip:** For new features, follow the patterns in `src/common/core/` and `src/ui/`. For integrations, reference the relevant subdirectory in `examples/` and `docs/`.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\n\nSource lives in `src/`: `api/` (FastAPI service), `ui/` (admin UI), `linux/` (distribution packages and service units), `bw/` and `common/` (core WAF logic), plus packaging targets like `all-in-one/` and other platform bundles. Integration assets and manifests are under `examples/`, while reusable configuration templates live in `env/`. MkDocs content for docs.bunkerweb.io sits in `docs/`. System tests, fixtures, and helper scripts are consolidated in `tests/`.\n\n## Build, Test, and Development Commands\n\nBootstrap Python deps per component, e.g. `pip install -r src/api/requirements.txt` or `pip install -r src/ui/requirements.txt`. Build a full appliance image with `docker build -f src/all-in-one/Dockerfile .`. Exercise integrations locally via `python tests/main.py docker`; swap `docker` for `linux`, `autoconf`, `swarm`, or `kubernetes` as needed (set the matching `TEST_DOMAIN*` env vars first). Regenerate docs with `mkdocs serve --watch` from the repo root. Run `pre-commit run --all-files` before pushing to execute the standard formatters and linters.\n\n## Coding Style & Naming Conventions\n\nPython uses Black (160 char lines) and Flake8 with ignores defined in `.pre-commit-config.yaml`; prefer snake_case for modules and functions, PascalCase for classes. Lua code is formatted with StyLua (see `stylua.toml`) and linted with Luacheck; follow lowercase module names and descriptive function names. Shell scripts must pass ShellCheck and stay POSIX-compatible unless a `#!/bin/bash` shebang is explicit. Front-end assets follow Prettier defaults.\n\n## Testing Guidelines\n\nHigh-level acceptance suites live in `tests/` and orchestrate Dockerized environments—verify Docker access and required `TEST_DOMAIN*` env vars before running. Add scenario files under `examples/<use-case>/tests.json` with descriptive names; tests should assert observable behavior rather than internals. For unit-style Python additions, provide lightweight checks inside the relevant module and hook them into integration flows when feasible. Capture regressions by replicating failing requests in the automated suites.\n\n## Commit & Pull Request Guidelines\n\nUse concise, present-tense messages; the history favors Conventional Commits (`feat:`, `fix:`, `docs:`) or `<component> - …` prefixes. Reference issue IDs when closing or relating tickets. Each PR should include a summary of changes, validation steps (commands or screenshots for UI changes), and updated docs or config when behavior shifts. Coordinate breaking changes with maintainers and flag them clearly in both commit body and PR description.\n\n## Security & Configuration Tips\n\nNever commit secrets—use sample files in `env/` or add new templates when introducing config. Review `.gitleaksignore` before adjusting dependencies. Docker Scout is used for container image vulnerability scanning in CI/CD—check the `container-build.yml` workflow for current scan configuration. When touching TLS, keys, or rule bundles, document rotation steps and default hardening in the accompanying docs update.\n","category":"root","tokens":779},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nBunkerWeb is an open-source Web Application Firewall (WAF) built on NGINX with a modular plugin architecture. It provides \"security by default\" for web services through multiple integration modes (Docker, Kubernetes, Swarm, Linux) and is fully configurable via environment variables.\n\n## Architecture\n\n### Core Components\n\n- **BunkerWeb Core** (`src/bw/`, `src/common/core/`): NGINX-based reverse proxy with security modules in Lua (request-time) and Python (jobs). Entry point: `src/bw/lua/bunkerweb.lua`.\n- **Scheduler** (`src/scheduler/`): Central orchestrator (\"brain\"). `main.py` runs the main loop; `JobScheduler.py` manages job execution with thread pools. Uses Python's `schedule` library.\n- **Autoconf** (`src/autoconf/`): Listens for Docker/Swarm/Kubernetes events and dynamically reconfigures BunkerWeb.\n- **API** (`src/api/`): FastAPI service with router-based architecture (`src/api/app/routers/` — auth, instances, services, configs, plugins, jobs). IP whitelist and rate limiting support.\n- **Web UI** (`src/ui/`): Flask app using Blueprints for routing (`src/ui/app/routes/` — configs, plugins, jobs, logs, instances, profile, etc.). Uses Flask-Login for auth and Jinja2 templates. `dependencies.py` is the central dependency injection point providing DB, DATA, BW_CONFIG, BW_INSTANCES_UTILS.\n- **Database** (`src/common/db/`): SQLAlchemy ORM with `model.py` defining all tables (Plugins, Settings, Services, Jobs, Custom_configs, Users, etc.). `Database.py` wraps high-level query methods. Supports SQLite (WAL mode), MariaDB, MySQL, PostgreSQL with QueuePool for connection pooling.\n\n### Configuration Flow\n\n1. Settings defined as environment variables (e.g., `USE_ANTIBOT=captcha`, `AUTO_LETS_ENCRYPT=yes`)\n2. Scheduler reads settings from environment or database\n3. **Configurator** (`src/common/gen/Configurator.py`) validates settings against `plugin.json` schemas with pre-compiled regex caches\n4. **Templator** (`src/common/gen/Templator.py`) renders NGINX configs from Jinja2 templates (`src/common/confs/`) using ProcessPoolExecutor for parallel rendering\n5. BunkerWeb instances reload with new configuration\n6. In multisite mode, prefix settings with server name: `www.example.com_USE_ANTIBOT=captcha`\n7. Multiple settings use numeric suffixes: `REVERSE_PROXY_URL_1=/api`, `REVERSE_PROXY_HOST_1=http://backend1`\n\n### Plugin System\n\nEach core module in `src/common/core/*/` contains:\n\n- `plugin.json`: Metadata with settings schema (id, name, version, stream, settings with context/type/regex/default, jobs array with schedule/reload/async flags)\n- `jobs/` folder: Python scripts for periodic tasks (e.g., downloading blocklists). Jobs specify `every` (once/minute/hour/day/week) and `reload` flag.\n- Lua code for request-time processing\n- `confs/` folder: NGINX configuration templates\n\nExternal plugins follow the same structure.\n\n### Lua Request Processing Pipeline\n\nThe Lua runtime (`src/bw/lua/`) processes requests through plugin hooks at NGINX phases: access, header_filter, body_filter, log. Key files:\n\n- `plugin.lua`: Plugin loader and execution across phases\n- `ctx.lua`: Per-request context management\n- `datastore.lua`: Shared data persistence (shared dict backed)\n- `cachestore.lua`: Request-level caching\n- `clusterstore.lua`: Cluster-aware storage (Redis)\n\n### Core Plugins (src/common/core/)\n\n42 plugins organized by function:\n\n- **Auth**: antibot (CAPTCHA), authbasic, mtls, crowdsec\n- **Threat Detection**: modsecurity (OWASP WAF), badbehavior, dnsbl, reversescan\n- **Access Control**: whitelist, blacklist, greylist, country, limit (rate limiting)\n- **SSL/TLS**: ssl, letsencrypt, customcert, selfsigned\n- **Proxy & Routing**: reverseproxy, realip, redirect, grpc, php\n- **Performance**: gzip, brotli, clientcache, redis\n- **Headers & Content**: headers, cors, inject, robotstxt, securitytxt\n- **Management**: sessions, metrics, backup, templates, bunkernet, ui, db, jobs\n\n### Shared Utilities (src/common/utils/)\n\n- `common_utils.py`: Docker secrets handling, hashing, version info, integration detection\n- `logger.py`: Logging with syslog support\n- `jobs.py`: Job helpers (atomic writes, file hashing, tar operations)\n- `ApiCaller.py`: HTTP client for inter-component API calls\n\n## Development Commands\n\n### Setup\n\n```bash\npip install -r src/scheduler/requirements.txt\npip install -r src/ui/requirements.txt\npip install -r src/api/requirements.txt\npre-commit install\n```\n\n### Build\n\n```bash\n# Build Docker image (all-in-one)\ndocker build -f src/all-in-one/Dockerfile -t bunkerweb:dev .\n\n# Build specific component\ndocker build -f src/scheduler/Dockerfile -t bunkerweb-scheduler:dev .\ndocker build -f src/ui/Dockerfile -t bunkerweb-ui:dev .\n```\n\n### Linting & Formatting\n\n```bash\n# Run all pre-commit hooks\npre-commit run --all-files\n\n# Individual tools\nblack .                          # Python formatting (160 char lines)\nflake8 .                         # Python linting (ignores E266,E402,E501,E722,W503)\nstylua .                         # Lua formatting\nluacheck src/                    # Lua linting (--std min)\nshellcheck scripts/*.sh          # Shell script linting\nprettier --write \"**/*.{js,ts,css,html,json,yaml,md}\"  # Frontend formatting\ncodespell                        # Spell checking\nrefurb                           # Python refactoring suggestions (excludes tests/)\n```\n\n### Run Development Instance\n\n```bash\n# Full stack with UI + API (recommended)\ndocker compose -f misc/dev/docker-compose.ui.api.yml up -d\n```\n\nDev compose files in `misc/dev/`:\n\n- `docker-compose.ui.api.yml` — Full stack (UI + API + core + MariaDB) — **recommended**\n- `docker-compose.ui.yml` — UI only (no API)\n- `docker-compose.all-in-one.yml` — Single container with all components\n- `docker-compose.autoconf.yml` — Docker autoconf mode\n- `docker-compose.wizard.yml` — Setup wizard\n\nDev credentials: UI `admin`/`P@ssw0rd`, API `admin`/`P@ssw0rd`, DB `bunkerweb`/`secret`.\n\nThe dev compose mounts `src/ui/app/` and `src/api/app/` as read-only volumes, so UI and API code changes apply without rebuilding (restart the container to pick up changes).\n\n### Database Migrations\n\n```bash\n# Alembic migrations in src/common/db/alembic/\n# Separate version directories per DB type: mariadb_versions, mysql_versions, postgresql_versions, sqlite_versions\n# Migration scripts also in src/common/db/alembic/\n```\n\n## Key Files\n\n- `src/common/settings.json`: Master list of all core settings with validation rules\n- `src/common/db/model.py`: SQLAlchemy ORM models for all tables\n- `src/common/db/Database.py`: High-level database wrapper\n- `src/common/gen/Configurator.py`: Settings validation engine\n- `src/common/gen/Templator.py`: NGINX config renderer\n- `src/scheduler/main.py`: Scheduler entry point\n- `src/scheduler/JobScheduler.py`: Job execution orchestrator\n- `src/ui/main.py`: Web UI entry point\n- `src/ui/app/dependencies.py`: UI dependency injection (DB, DATA, BW_CONFIG)\n- `src/api/app/core.py`: API entry point (imports all routers)\n- `src/bw/lua/bunkerweb.lua`: Main Lua runtime initialization\n- `pyproject.toml`: Black config (160 char lines)\n- `.pre-commit-config.yaml`: All linting/formatting rules\n\n## Important Patterns\n\n### Settings Context\n\n- `global`: Applied to all servers (e.g., `WORKER_PROCESSES`, `LOG_LEVEL`)\n- `multisite`: Can be server-specific (prefix with `SERVER_NAME_`)\n\n### Security Modes\n\n- `detect`: Log threats without blocking\n- `block`: Actively block threats (default)\n\n### Integration Modes\n\nSet one of these to `yes`: `AUTOCONF_MODE`, `SWARM_MODE`, `KUBERNETES_MODE`\n\n### Testing\n\n```bash\npython3 tests/main.py docker              # Docker integration tests\npython3 tests/main.py autoconf            # Autoconf tests\npython3 tests/main.py swarm               # Swarm tests\npython3 tests/main.py kubernetes           # Kubernetes tests\npython3 tests/main.py linux debian         # Linux tests (with distro)\n```\n\n- Tests scan `examples/*/tests.json` for test scenarios (type: string/status, url, expected results)\n- Real Docker environments with actual HTTP requests — tests verify observable behavior, not internals\n\n## Key Conventions\n\n- Python: snake_case (modules/functions), PascalCase (classes), Black formatting at 160 chars\n- Lua: lowercase module names, descriptive function names, StyLua formatting\n- Shell: POSIX-compatible unless `#!/bin/bash` shebang, pass ShellCheck\n- Commit messages: Conventional Commits (`feat:`, `fix:`, `docs:`) or `<component> - ...` format\n- UI translations in `src/ui/app/static/locales/`\n\n## External Resources\n\n- Documentation: <https://docs.bunkerweb.io>\n- Official Plugins: <https://github.com/bunkerity/bunkerweb-plugins>\n- Web UI Demo: <https://demo-ui.bunkerweb.io>\n","category":"root","tokens":2204},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# Copilot Instructions for BunkerWeb\n\n## Project Overview\n\n- **BunkerWeb** is a next-generation, open-source Web Application Firewall (WAF) built on top of NGINX, with a modular, plugin-based architecture.\n- Major components: core (security logic), scheduler (configuration and job orchestration), web UI (management), plugin system (feature extension), and integrations (Docker, Kubernetes, Swarm, Linux, Azure).\n- Configuration is driven by environment variables (settings), custom NGINX/ModSecurity configs, and a backend database (SQLite, MariaDB, MySQL, PostgreSQL).\n\n## Key Directories\n\n- `src/`: Main source code (core, scheduler, plugins, UI, integrations)\n- `docs/`: Documentation, guides, and assets\n- `examples/`: Real-world configuration and deployment examples\n- `tests/`: Test scripts and scenarios\n- `misc/`: Utilities, scripts, and ASCII art\n\n## Developer Workflows\n\n- **Build/Run**: See `docs/quickstart-guide.md` and `README.md` for integration-specific instructions (Linux, Docker, Kubernetes, etc.).\n- **Testing**: Use scripts in `tests/` (e.g., `main.py`, `AutoconfTest.py`, `SwarmTest.py`).\n- **Debugging**: Logs and job execution are managed by the scheduler; use the web UI for live monitoring and troubleshooting.\n- **Plugins**: Add new features by placing plugins in the appropriate directory and updating settings. See `docs/plugins.md` and the [bunkerweb-plugins repo](https://github.com/bunkerity/bunkerweb-plugins).\n\n## Project-Specific Conventions\n\n- **Settings**: All configuration is via environment variables (e.g., `USE_ANTIBOT=captcha`). In multisite mode, prefix with the server name (e.g., `www.example.com_USE_ANTIBOT=captcha`).\n- **Multiple values**: Use numbered suffixes for repeated settings (e.g., `REVERSE_PROXY_URL_1`, `REVERSE_PROXY_URL_2`).\n- **Custom configs**: Place NGINX/ModSecurity customizations in designated config files or via the web UI.\n- **Localization**: UI translations in `src/ui/app/static/locales/`.\n\n## Integration Patterns\n\n- **Scheduler** is the central orchestrator for config, jobs, and service communication.\n- **Autoconf** listens for environment events (Docker, Swarm, Kubernetes) and updates config in real time.\n- **Web UI** interacts with the scheduler/database for live management.\n- **Plugins** extend core via settings and hooks; see plugin README files for details.\n\n## Examples\n\n- See `examples/` for integration and configuration samples.\n- See `src/common/core/` for core security modules (each with its own README).\n\n## External Resources\n\n- [Documentation](https://docs.bunkerweb.io)\n- [Web UI Demo](https://demo-ui.bunkerweb.io)\n- [Plugins](https://github.com/bunkerity/bunkerweb-plugins)\n\n## Contributing\n\n- Follow the [CONTRIBUTING.md](../CONTRIBUTING.md) and [SECURITY.md](../SECURITY.md) guidelines.\n- Use the [web UI](https://docs.bunkerweb.io/web-ui/) for most configuration and debugging tasks.\n\n---\n\n**Tip:** For new features, follow the patterns in `src/common/core/` and `src/ui/`. For integrations, reference the relevant subdirectory in `examples/` and `docs/`.\n","category":".github","tokens":765}]}