Skip to content

Network Security

This page explains how Campus WoL protects data in transit, restricts cross-origin access, applies security headers, rate-limits operational endpoints, and validates input.

TLS Termination

The Campus WoL application listens on plain HTTP internally. It does not handle TLS (HTTPS) directly. Instead, it expects an external reverse proxy (such as Nginx, Caddy, or Traefik) to terminate TLS and forward requests to the application.

What is a reverse proxy?

A reverse proxy sits between the internet and your application. It accepts incoming HTTPS connections from users, decrypts them, and forwards the requests to the application over a private internal connection. This means the application itself does not need to manage TLS certificates -- the proxy handles all of that. Most production deployments already use a reverse proxy for load balancing and certificate management.

This architecture is standard for containerized web applications and allows administrators to use their existing certificate management infrastructure (such as Let's Encrypt or organizational CA certificates) without modifying the application.

CORS

Cross-Origin Resource Sharing (CORS) controls which websites can make requests to the Campus WoL API. By default, the application is configured to accept requests from http://127.0.0.1:8443.

In production, set the ALLOWED_ORIGINS environment variable to the actual origin of your deployment (e.g., https://wol.example.edu). The application restricts API access to requests originating from this configured origin. All HTTP methods and headers are permitted from the allowed origin, but requests from any other origin are rejected.

What is CORS?

CORS is a browser security feature that prevents a web page on one domain from making requests to a different domain unless the server explicitly allows it. By restricting the allowed origin to your deployment's URL, Campus WoL ensures that only your site's pages can interact with the API -- a malicious page on another domain cannot make requests on behalf of a logged-in user.

Security Headers

The application sets the following HTTP security headers on all responses:

Header Value Purpose
X-Frame-Options DENY Prevents the application from being embedded in iframes, blocking clickjacking attacks
X-Content-Type-Options nosniff Prevents browsers from guessing content types, reducing the risk of certain injection attacks
Content-Security-Policy default-src 'self' Restricts all resource loading to the same origin, preventing cross-site scripting via injected scripts or styles

These headers are applied automatically and do not require configuration.

Rate Limiting

Campus WoL applies rate limiting to protect against abuse of both the login and operational endpoints:

Endpoint Limit Window
Login 10 attempts 5-minute sliding window
Wake operations 30 requests Per minute (configurable)

The wake operations rate limit prevents automated scripts or misconfigured integrations from flooding the system with wake requests. The default limit of 30 per minute is configurable through environment variables.

Both rate limiters use a token bucket algorithm, which allows short bursts of activity while enforcing the average rate over time.

What is a token bucket?

A token bucket is a rate-limiting approach where a "bucket" holds a fixed number of tokens. Each request consumes one token. Tokens refill at a steady rate over time. If the bucket is empty, the request is rejected. This allows brief bursts of activity (e.g., waking 20 devices at once) while still enforcing a limit over time.

Input Validation

All data submitted to the API is validated before processing. The application uses Pydantic models to enforce strict type and format requirements on incoming data:

  • MAC addresses -- Must match the standard MAC address format
  • IP addresses -- Must be valid IPv4 or IPv6 addresses
  • VLAN ranges -- Must be within the valid VLAN ID range
  • Cron expressions -- Must follow valid cron syntax for schedule definitions

Requests with invalid input are rejected with a clear error message before any processing occurs. This prevents malformed data from entering the system and reduces the surface area for injection attacks.

Next Steps