Elgato_dark/bunkerweb
1
0
Fork 0
mirror of https://github.com/bunkerity/bunkerweb synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
bunkerweb/examples/mcp-stack/CLAUDE.md

4.7 KiB
Raw Permalink Blame History

BunkerWeb MCP Stack

This example deploys BunkerWeb with its MCP server, giving AI assistants (Claude Code, Claude Desktop, etc.) full management capabilities over the WAF through the Model Context Protocol.

For comprehensive BunkerWeb documentation, see docs.bunkerweb.io.

Quick Start

docker compose up -d

Then configure your AI assistant to use the MCP server. For Claude Code, copy .mcp.json to your project root or to ~/.claude/.mcp.json for global access.

Key Concepts

Concept Description
Instance A BunkerWeb node (NGINX process). Can be reloaded, started, stopped.
Service A virtual host / server block. Has a SERVER_NAME and can be online or draft.
Global config Settings shared across all services. Overridable per-service.
Custom config NGINX or ModSecurity snippets injected at specific contexts (http, server-http, modsec, modsec-crs).
Ban Dynamic IP block — temporary or permanent, global or per-service.
Job Scheduled task run by a plugin (e.g., downloading blocklists, refreshing CRS rules).
Cache Data files generated by jobs (IP lists, GeoIP DBs, CRS rules). Stored per-plugin.

MCP Resources

Read-only resources available via the @ syntax:

Resource Content
@config://global Current global configuration
@instances://status Health and status of all instances
@bans://active Currently active IP bans
@logs://jobs Job execution history

Example: "Review @config://global and suggest security hardening improvements"

Tool Safety Guide

Safe (read-only)

ping, health, list_*, get_*, and @ resources.

Modifying (auto-applied by BunkerWeb)

create_*, update_*, global_config_update, ban_ip, jobs_run. No manual reload needed — BunkerWeb applies changes automatically.

Destructive (confirm before using)

delete_*, unban_ip, stop_*. These remove data or interrupt services.

Common Workflows

Deploy a new service

  1. create_service with is_draft: true and server_name: "example.com"
  2. Add custom configs if needed via config_create
  3. convert_service with convert_to: "online" when ready

Investigate a security incident

  1. Read @bans://active — look for patterns (country, ASN, timing)
  2. ban_ip with a meaningful reason and appropriate expiry
  3. Add custom ModSecurity rules via config_create (type: modsec-crs) if needed

Refresh threat intelligence

  1. Check @logs://jobs for last successful runs
  2. jobs_run with the target jobs, e.g.: [{"plugin": "blacklist", "name": "download-blacklist"}]
  3. Verify with cache_list for the relevant plugin

Fix a corrupt cache

  1. cache_delete_file to remove the bad file
  2. jobs_run to regenerate it
  3. Verify via cache_list

Troubleshooting

Symptom Steps
ping / health fails Check that bw-api and bw-mcp containers are running and on the same network
Config changes have no effect Verify instance status with list_instances; check instance_ping
Service unreachable Confirm SERVER_NAME matches DNS; check the service isn't still in draft mode
Jobs failing Read @logs://jobs for errors; verify network access and disk space

Security Notes

  • Never commit secrets — API tokens, session secrets, and keys belong in environment variables or a secrets manager.
  • Use HTTPS in production — the MCP server in this example listens on plain HTTP, suitable for local development only.
  • Rotate BUNKERWEB_API_TOKEN regularly in production environments.
  • DNS rebinding protection is disabled in this example (MCP_ENABLE_DNS_REBINDING_PROTECTION=False). Enable it in production and set MCP_ALLOWED_HOSTS explicitly.
  • Always provide a reason when banning IPs — it creates an audit trail.