diff --git a/README.md b/README.md index 6c051e6..ac744f8 100644 --- a/README.md +++ b/README.md @@ -20,25 +20,40 @@ ## Quick start +### 1. Download the starter files + +Create a directory and download the required files: + ```bash -docker run -d \ - --name aegis \ - -p 8765:8765 \ - -v aegis_data:/data \ - -e ADMIN_PASSWORD=changeme \ - axieyangb/aegis:latest +mkdir aegis && cd aegis + +# Download docker-compose config +curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml + +# Download Envoy static bootstrap config +mkdir envoy +curl -o envoy/envoy.yaml https://raw.githubusercontent.com/axieyangb/aegis/main/envoy/envoy.yaml + +# Download baseline database configuration +mkdir configs +curl -o configs/starter.json https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json ``` -Open `http://localhost:8765` — default login: `admin` / `changeme` - -### With Envoy (recommended) +### 2. Start the gateway ```bash -curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml -curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json docker compose up -d ``` +* Open **`http://localhost:8765`** — default login: `admin` / `changeme` (Change the `ADMIN_PASSWORD` in `docker-compose.yml`!). + +### 3. Import the baseline configuration + +* Go to the **Gateway** page in the dashboard. +* Click the **Import** button at the top right. +* Upload the `configs/starter.json` file you downloaded. +* You should see the `http_listener` and `https_listener` appear, and the xDS sync status turn green! + --- ## Features in Action @@ -152,10 +167,8 @@ ## Docs -- [Getting started](docs/getting-started.md) -- [Envoy configuration](docs/envoy-config.md) -- [AI setup (Owl chat + threat analysis)](docs/ai-setup.md) -- [Notifications (Telegram, Discord, webhooks)](docs/notifications.md) +* [Getting started](docs/getting-started.md) +* [Envoy configuration](docs/envoy-config.md) --- @@ -191,5 +204,5 @@ ## Support & Enterprise -- **Issues & feature requests**: [GitHub Issues](https://github.com/axieyangb/aegis/issues) -- **Enterprise collaboration, custom integrations, or just want to know more**: [yyangxie@gmail.com](mailto:yyangxie@gmail.com) +* **Issues & feature requests**: [GitHub Issues](https://github.com/axieyangb/aegis/issues) +* **Enterprise collaboration, custom integrations, or just want to know more**: [yyangxie@gmail.com](mailto:yyangxie@gmail.com) diff --git a/docker-compose.yml b/docker-compose.yml index fbcde0a..e09e43c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -24,11 +24,11 @@ - "80:10080" - "443:10443" volumes: - - ./configs/starter.json:/etc/envoy/envoy.json:ro + - ./envoy/envoy.yaml:/etc/envoy/envoy.yaml:ro command: - /usr/local/bin/envoy - -c - - /etc/envoy/envoy.json + - /etc/envoy/envoy.yaml - --log-level - warn networks: diff --git a/docs/envoy-config.md b/docs/envoy-config.md index 9f1d56b..c34996d 100644 --- a/docs/envoy-config.md +++ b/docs/envoy-config.md @@ -1,67 +1,31 @@ # Envoy Configuration -Aegis controls Envoy via xDS (ADS protocol). You configure everything through the Aegis UI — no manual YAML editing required. +Aegis controls Envoy via xDS (specifically using the ADS - Aggregated Discovery Service - protocol). You configure everything through the Aegis UI — no manual YAML editing required. ## How it works -1. Envoy connects to Aegis at `aegis:18000` (gRPC ADS) -2. Aegis pushes listeners, clusters, and secrets dynamically -3. Changes in the Aegis UI take effect in Envoy within ~1 second +1. Envoy starts using a static bootstrap file (`envoy.yaml`) pointing it to Aegis. +2. Envoy connects to Aegis at `aegis:18000` (gRPC ADS). +3. Aegis pushes listeners, clusters, and secrets dynamically from its database. +4. Changes made in the Aegis UI take effect in Envoy within ~1 second. -## Static bootstrap (envoy.yaml / starter.json) +## Static bootstrap (`envoy.yaml`) -Envoy needs a static bootstrap file to know where to find the xDS server. The provided `configs/starter.json` configures: +Envoy needs a static bootstrap file to know where to find the xDS server. The provided `envoy/envoy.yaml` configures: -- xDS server: `aegis:18000` -- Access log: streamed to Aegis via gRPC ALS (provides real-time traffic data) -- Node ID: `home` (must match `NODE_ID` env var in Aegis) +* **xDS server:** `aegis:18000` (using gRPC). +* **Node ID:** `home` (must match `NODE_ID` env var in Aegis). +* **Admin interface:** bound to port `9901` (internal or public as mapped in docker-compose). -**Do not add listeners or clusters to the bootstrap file** — manage them entirely through the Aegis Gateway UI. +**Do not add listeners or clusters to this bootstrap file.** They should be managed entirely through the Aegis Gateway UI (and are stored in Aegis's database). -## Gateway concepts +## Dynamic configuration (`starter.json`) -### Listeners -A listener binds to a port and accepts connections. Typically: -- One listener on port 80 (HTTP) -- One listener on port 443 (HTTPS) +The `configs/starter.json` is **not** read by Envoy. It is an export of the Aegis database structure. When imported via the Aegis UI, it configures: -### Filter chains -Each listener can have multiple filter chains. A filter chain matches incoming connections (by SNI/domain) and routes them to a backend cluster. Each filter chain can have: -- A TLS secret (for HTTPS) -- A backend cluster -- HTTP extensions (OIDC, rate limiting, Lua, etc.) +* `http_listener` (port 10080): Redirects all standard HTTP traffic to HTTPS, but routes `/.well-known/acme-challenge` to the `acme-renewer` cluster. +* `https_listener` (port 10443): Placeholder for your SSL traffic with SNI matching. +* `acme-renewer` cluster: Points to Aegis's built-in ACME challenge responder. +* `my-service` cluster: Placeholder for your actual backend application. -### Clusters -An upstream cluster defines where traffic goes. Types: -- `STATIC` — fixed IP/hostname (resolved once at startup) -- `LOGICAL_DNS` — resolve hostname once and cache -- `STRICT_DNS` — resolve on every connection - -### Secrets (SDS) -TLS certificates stored in Envoy's Secret Discovery Service. Aegis manages these automatically when you issue certificates via the Certs page. - -## Common setups - -### Reverse proxy for a single service - -1. Create a cluster pointing to your service (e.g. `192.168.1.10:3000`) -2. Add an HTTPS listener on port 443 -3. Add a filter chain: domain = `app.example.com`, cluster = your cluster, TLS = your cert - -### Multiple domains on one server - -Add one filter chain per domain to your HTTPS listener. Each filter chain has its own SNI match, backend cluster, and TLS secret. - -### HTTP → HTTPS redirect - -Add a catch-all filter chain on the port-80 listener with a Lua HTTP filter that returns a 301 redirect. - -## Blocked IPs - -Blocked IPs are automatically injected as Envoy RBAC deny rules on every xDS push. You do not need to configure this. - -## Troubleshooting - -**"xDS NACK"** in the dashboard header means Envoy rejected the last config. The error message shows which resource failed. Fix the highlighted resource and save again. - -**Changes not applying** — check that the xDS status is "synced" (green dot). If it shows "xDS …" (grey), Envoy is not connected — verify the `NODE_ID` env var matches the node ID in your bootstrap config. +Once imported, Aegis dynamically translates these into Envoy-native config and pushes them to Envoy over the xDS channel. diff --git a/docs/getting-started.md b/docs/getting-started.md index a8a212a..a2b140b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -9,9 +9,19 @@ ## 1. Download the starter files +Create a new directory for Aegis and download the required configuration files: + ```bash mkdir aegis && cd aegis + +# Download docker-compose config curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml + +# Download Envoy bootstrap configuration +mkdir envoy +curl -o envoy/envoy.yaml https://raw.githubusercontent.com/axieyangb/aegis/main/envoy/envoy.yaml + +# Download baseline database configuration mkdir configs curl -o configs/starter.json https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json ``` @@ -20,39 +30,26 @@ Edit `docker-compose.yml` and change `ADMIN_PASSWORD=changeme` to something secure. -## 3. Start +## 3. Start the gateway ```bash docker compose up -d ``` -Aegis dashboard: `http://localhost:8765` -Default login: `admin` / (your password) +* Aegis dashboard: `http://localhost:8765` +* Default login: `admin` / (your password) -## 4. Connect Envoy to Aegis +## 4. Connect Envoy to Aegis (Importing baseline) -The starter config in `configs/starter.json` already points Envoy's xDS endpoint at `aegis:18000`. Envoy will connect automatically once both containers are running. +1. Open the Aegis dashboard in your browser. +2. Go to **Gateway** page. +3. Click the **Import** button at the top right. +4. Upload the `configs/starter.json` file you downloaded in Step 1. -Open **Gateway** in the dashboard — you should see "xDS synced" in green. +This will seed Aegis's database with a standard baseline configuration (a port 80 listener that redirects to HTTPS and handles ACME challenges). Aegis will immediately generate the correct Envoy configuration and push it to Envoy via xDS. -## 5. Add your first listener +You should see **"xDS synced"** in green on the Gateway page, confirming Envoy has successfully connected and loaded the configuration! -Go to **Gateway → Listeners → Add filter chain**. Configure your domain, backend cluster, and TLS secret. Changes push to Envoy immediately. +## 5. Add your first service -## 6. Issue a TLS certificate - -Go to **Certificates → Add Provider** and configure an ACME provider (Let's Encrypt + HTTP-01 is the easiest). Then **Issue Certificate** for your domain. - -> **Note:** HTTP-01 requires the `acme-renewer` cluster and a port-80 filter chain. Open the Owl chat and say "Help me set up HTTP-01" — it will walk you through the gateway configuration. - -## 7. Enable AI (optional) - -Go to **Settings → AI**, enable Intelligence Review, and enter an API key for your chosen provider (Gemini, Claude, OpenAI, DeepSeek, or Ollama for local inference). Aegis will start classifying IPs in the background. - -Enable **Owl Chat** to talk to your gateway in natural language. - -## Next steps - -- [Envoy configuration reference](envoy-config.md) -- [AI setup](ai-setup.md) -- [Notifications](notifications.md) +Go to **Gateway → Clusters** to configure your backend services, and **Gateway → Listeners** to edit the `https_listener` filter chains to route your domain to your new cluster. diff --git a/envoy/envoy.yaml b/envoy/envoy.yaml new file mode 100644 index 0000000..7d5cb49 --- /dev/null +++ b/envoy/envoy.yaml @@ -0,0 +1,50 @@ +node: + id: home + cluster: aegis + +# All dynamic resources (listeners, clusters, secrets) come from Aegis via ADS. +dynamic_resources: + ads_config: + api_type: GRPC + transport_api_version: V3 + grpc_services: + - envoy_grpc: + cluster_name: xds_cluster + lds_config: + resource_api_version: V3 + ads: {} + cds_config: + resource_api_version: V3 + ads: {} + +static_resources: + clusters: + # xds_cluster is the only static cluster — used for both xDS and ALS gRPC to Aegis. + - name: xds_cluster + type: STRICT_DNS + connect_timeout: 5s + typed_extension_protocol_options: + envoy.extensions.upstreams.http.v3.HttpProtocolOptions: + "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions + explicit_http_config: + http2_protocol_options: {} + load_assignment: + cluster_name: xds_cluster + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: aegis + port_value: 18000 + +admin: + address: + socket_address: + address: 0.0.0.0 + port_value: 9901 + access_log: + - name: envoy.access_loggers.file + typed_config: + "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog + path: /dev/null