simple_app

command
v2.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 12 Imported by: 0

README

echo-guard simple app

A minimal guarded Echo server in a single main.go, wired to the guard-core-go engine through the echo-guard adapter middleware. It shows the canonical wiring and what the adapter does for you: request translation, bounded body scanning with body replay, exact verdict translation (status, headers, body, then the chain stops), and fail-closed 500s on engine malfunction.

For a production-style layout (route registry, admin routes, graceful shutdown), see ../advanced_app.

Run it

With Docker Compose (recommended, includes Redis):

cd examples/simple_app
docker compose up --build

Or with the Go toolchain (in-process state, no Redis needed):

go run ./examples/simple_app

Endpoints

Endpoint What it demonstrates
GET / API info; passes the guard
GET /health Liveness probe; excluded from the pipeline via ExcludePaths
POST /echo Body-bearing request; the adapter replays the body so the handler reads it untouched after the engine scans its bounded prefix
GET /rate/strict Per-endpoint rate limit: 1 request per 10 seconds (EndpointRateLimits)
GET /search?q=... Query parameter scanning; XSS payloads trip the demo xss threat ban (threshold 1) and the verdict carries the custom 403 body

Try the security behavior

# Allowed
curl -i http://localhost:8080/

# Rate limited: the second request within 10 seconds returns 429
curl -i http://localhost:8080/rate/strict
curl -i http://localhost:8080/rate/strict

# Blocked: the XSS payload trips the xss threat ban (demo threshold 1) and
# the verdict carries the custom 403 body
curl -i -G http://localhost:8080/search --data-urlencode 'q=<script>alert(1)</script>'

# The client IP is now banned: every request returns the custom 403 body
curl -i http://localhost:8080/

A note on address headers

The engine skips ssrf scanning for address headers (host, x-forwarded-for, x-real-ip, ...) through its built-in default set (guardcore.DefaultExcludedHeaders), as the reference does, so a plain Host: localhost request is not flagged and main.go needs no ExcludedDetectionHeaders entry. That field only adds names on top of the default.

Configuration knobs demonstrated

Inline comments in main.go walk through every knob used:

  • Global rate limiting (RateLimit, RateLimitWindow) and per-endpoint overrides (EndpointRateLimits)
  • Auto-banning (AutoBanThreshold, AutoBanDuration) plus a per-threat ban (ThreatBanConfig for xss)
  • Penetration detection with all categories enabled
  • Blocked user agents (regex patterns)
  • CustomErrorResponses for consistent block bodies
  • ExcludePaths for health and docs routes
  • Redis via REDIS_URL / REDIS_PREFIX (compose wires Redis in; without it the managers fall back to in-process state)
  • The OnBlock hook: the telemetry seam for wiring guard-agent-go (comment-level guidance in main.go; EnableAgent validates but streams only to a guardcore.AgentHandler set in AgentHandler, so the example keeps it off)

Echo notes

  • Import the adapter with an explicit alias: the package name is echo, which collides with github.com/labstack/echo/v5 (also package echo); guardecho is the idiomatic alias.
  • guardecho.New(engine) returns an echo.MiddlewareFunc, so it composes with e.Use and can sit anywhere in a chain. Keep it as early as possible so blocked requests never reach your other middleware; echomiddleware.Recovery() stays outermost so handler panics are contained. Echo has no explicit abort call: the guard writes the verdict to c.Response() and the chain stops because it returns nil without calling next(c).
  • guardecho.WithMaxBodyBytes bounds the body bytes the engine scans (default 262144); bytes beyond the bound are not scanned, and the full body still reaches your handler through the adapter's replay wrapper.

Environment variables

Variable Default Purpose
REDIS_URL (unset; Redis disabled) When set, bans and rate limits are shared through Redis
REDIS_PREFIX guard_core: Redis key prefix

Module layout note

Both example apps live inside the root module (github.com/rennf93/echo-guard/v2/examples/...) rather than in separate Go modules or a go.work workspace. Rationale: the examples pin the exact adapter they document (same module, same commit), so go vet ./... and go build ./... gate them together with the adapter in CI and the Dockerfiles COPY go.mod go.sum only once. Splitting them out would let an example drift against a published adapter version while still compiling. The tradeoff: the examples' imports resolve only inside this module, which is fine for copy-paste-driven reference code.

Documentation

Overview

Command simple_app is a minimal guarded Echo server. The Echo bridging lives in the echo-guard adapter (this repository) and every security decision comes from the guard-core-go engine, so the demonstration wiring is the canonical one:

SecurityConfig -> NewEngine -> Initialize -> guardecho.New -> e.Use

Unlike guard-core-go's own simple_app, no request shim is written here: the adapter performs request translation, bounded body scanning with replay, exact verdict translation, and fail-closed handling.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL