<p align="center"> <img src="https://veinar.pl/dracan.png" alt="logo" width="300"/>

<br> </p>

What is Dracan?

Dracan is a specialized software solution designed to enhance filtering and validation capabilities within Kubernetes (k8s) environments. It aims to be lightweight middleware between ingress and applications. This tool focuses on several key functionalities:

• HTTP Method Filtering: Dracan allows you to filter specific HTTP methods, ensuring that only allowed request types can interact with your applications.

• JSON Validation: It provides robust JSON validation to verify that incoming data meets predefined formats and standards, helping to prevent malformed data from causing issues in your applications.

• Request Limiting: Dracan enables you to set limits on the number of requests processed, helping to mitigate overload and protect application performance.

• Payload Limitation: Dracan supports payload limitation by allowing you to specify size limits for incoming request bodies. This feature helps prevent overly large requests that could impact application performance and stability.

• URI Filtering: Dracan supports filtering of incoming request URIs by allowing you to specify exact allowed URIs or use regular expressions for pattern matching. This ensures that only requests with valid URIs are processed, adding an extra layer of security and control.

• Header Validation: Dracan allows for comprehensive validation of HTTP headers in incoming requests. This functionality adds another level of control, ensuring that only requests with appropriate headers are processed, which can be crucial for maintaining application security and integrity. You can specify:

  • Required Headers: Ensure that specific headers must be present in the request.
  • Prohibited Headers: Specify headers that should not be included in the request.
  • Header Matching: Use regular expressions to validate header values or check for the presence of a header using a wildcard (*).

• You have another filtering/validation idea? Submit an issue! We are open for ideas :hearts:

Dracan is intended to serve as a gatekeeper for your applications, protecting them from erroneous or redundant queries. By ensuring the integrity of incoming requests, it contributes to operational continuity and safeguards against disruptive events.

Why use Dracan?

Dracan is a lightweight yet powerful middleware security solution for handling requests targeted at small to mid-sized development teams and independent projects. In a simple configuration file (understandable by developers), request validation can be set up with rate limiting, payload control, and traffic filtering enabled without advanced DevOps expertise or heavy infrastructure like WAF (Web application Firewall). You focus on creating good filters in rules_config.json, rest is on us.

Ideal for use for applications hosted on Kubernetes or GKE, Dracan offers essential security features to protect internal requests so that teams can focus on development. Because of its modular design, you are sure to be able to customize security needs with ease and speed. Dracan is both friendly and powerful for application protection.

Random requests performance test result could be found here.
Powershell script used for this test can be found here.

How to use it ?

<p align="center"> <img src="https://veinar.pl/dracan_diagram.gif" width="65%"> </p>

Dracan is designed to be implemented as middleware in Kubernetes (k8s) environments, functioning as a gatekeeper for your applications. Follow these steps to integrate Dracan into your system:

Example deployment can be seen in example subdirectory.

1. Deployment: Deploy Dracan in your Kubernetes cluster. It should be configured to replace the default application entry point in the Ingress controller.

2. Ingress Configuration: Set up Dracan as the primary Ingress resource. This will allow it to proxy requests to the designated services defined in your configuration file. Ensure that Dracan is correctly routed to the appropriate application services.

3. Configuration Files:

   • Proxy Configuration File proxy_config.json: This file should declare the services to which Dracan will proxy requests. It essentially tells Dracan how to route traffic.
   • Rules Configuration File rules_config.json: Use this file to specify the filtering, validation, and request limit rules that Dracan will enforce. You can define what types of HTTP methods to allow, set JSON validation schemas, and establish limits on the number of requests.

4. Deploy Changes: Apply the configuration changes and redeploy your Ingress resource. Dracan will now process incoming requests according to the defined rules, ensuring that only valid requests reach your application.

5. Monitor and Adjust: After deployment, monitor the traffic and performance. You may need to adjust the filtering and validation rules in the secondary configuration file based on your application's needs.

By following these steps, you can effectively integrate Dracan into your Kubernetes environment, enhancing the security and reliability of your applications.

Local development, testing and quality checking

To start developing Dracan on your local machine, you can set up a mock service for live debugging. Follow steps described in this doc to get started.

Docker

Docker image is present at DockerHub. For ease of use it is shipped without config JSONs. Remember to provide them on runtime!

You can also build image from source just follow this doc.

For further details on configuration of env variables, refer to this doc.

Configuration Files

To set up Dracan effectively, you need to create two configuration files: proxy_config.json and rules_config.json. These files determine how Dracan will handle incoming traffic and define the rules for validating, filtering, and limiting requests.

1. Creating proxy_config.json

The proxy_config.json file specifies where Dracan should proxy incoming traffic. Here’s a sample configuration:

{
    "destination": {
        "host": "127.0.0.1",
        "port": 8080,
        "path": "/"
    }
}

Expanded documentation about fields and values can be found HERE.

• host: The address of the destination service where Dracan will forward the requests. This can be an IP address or a domain name.

Make sure of correct DNS settings!

• port: The port on which the destination service is running.
• path: The path that will be appended to the host when forwarding requests.

Ensure this configuration accurately points to your application or mock service.

2. Creating rules_config.json

The rules_config.json file contains rules for validating, filtering, and limiting incoming requests. Below is an example configuration:

{
  "limiting_enabled": true,
  "rate_limit": "20 per minute",
  "method_validation_enabled": true,
  "allowed_methods": ["GET", "POST", "PUT", "DELETE"],
  "json_validation_enabled": true,
  "detailed_errors_enabled": false,
  "json_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "number" }
    },
    "required": ["name", "age"]
  },  
  "uri_validation_enabled": true,
  "allowed_uris": [
    "/health",
    "/data",
    "/update",
    "/delete"
  ],
  "allowed_uri_patterns": [
    "^/api/.*",               
    "^/public/[A-Za-z0-9_-]+"
  ],
  "payload_limiting_enabled": true,
  "max_payload_size": 1024,
  "header_validation_enabled": true,
  "required_headers": {
    "Content-Type": "application/json",
    "X-API-KEY": "*",
    "Authorization": "regex:^Bearer\\s[A-Za-z0-9\\-_]+\\.[A-Za-z0-9\\-_]+\\.[A-Za-z0-9\\-_]+$"
  },
  "prohibited_headers": [
    "X-Internal-Header",
    "X-Debug-Token"
  ]
}

Expanded documentation about fields and values can be found HERE.

• limiting_enabled: A boolean value that enables or disables rate limiting for incoming requests.
• rate_limit: Specifies the allowed rate of requests (e.g., "10 per minute"), how to check possible rates is described here.
• allowed_methods: An array of HTTP methods that are permitted for incoming requests (e.g., ["GET", "POST", "PUT", "DELETE"]).
• method_validation_enabled: A boolean flag to enable or disable validation of HTTP methods.
• json_validation_enabled: A boolean flag to enable or disable JSON body validation.
• detailed_errors_enabled: When set to true, Dracan pro