Skip to main content

Developer Guide

Comprehensive developer documentation for building, extending, and integrating with WolfGuard.

Overview​

This section is designed for developers who need to:

  • Understand WolfGuard's architecture and design
  • Use the REST API for automation and integration
  • Implement custom authentication or authorization
  • Contribute code or protocol improvements
  • Build integrations with external systems
  • Write tests and ensure compatibility

Developer Topics​

1. Reverse Engineering​

Comprehensive reverse engineering methodology for analyzing Cisco Secure Client:

2. Architecture​

Understand the system design:

3. API Reference​

Integrate with WolfGuard programmatically:

4. Code Examples​

Learn by example:

5. Protocol Implementation​

Deep dive into protocol details:

6. Integration​

Connect WolfGuard to external systems:

7. Testing​

Ensure quality and compatibility:

Quick Start for Developers​

Set Up Development Environment​

# Clone the repository
git clone https://github.com/dantte-lp/wolfguard.git
cd wolfguard

# Install dependencies (Ubuntu/Debian)
sudo apt-get install -y \
    build-essential cmake \
    libwolfssl-dev libev-dev \
    libreadline-dev check

# Build with debug symbols
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)

# Run tests
make test

Make Your First API Call​

# Get server status
curl -X GET https://vpn.example.com/api/v1/status \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# List active connections
curl -X GET https://vpn.example.com/api/v1/connections \
  -H "Authorization: Bearer YOUR_API_TOKEN"

See REST API Documentation for complete reference.

Architecture Overview​

┌─────────────────────────────────────────────────────────┐
│                   WolfGuard Architecture                 │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   REST API   │  │   WebUI      │  │   CLI Tool   │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                  │                  │          │
│         └──────────────────┴──────────────────┘          │
│                           │                              │
│                  ┌────────▼────────┐                     │
│                  │  Control Plane  │                     │
│                  │  - Auth/Authz   │                     │
│                  │  - Config Mgmt  │                     │
│                  │  - User Mgmt    │                     │
│                  └────────┬────────┘                     │
│                           │                              │
│         ┌─────────────────┴─────────────────┐            │
│         │                                   │            │
│  ┌──────▼──────┐                    ┌──────▼──────┐     │
│  │  TLS/HTTPS  │                    │ DTLS Tunnel │     │
│  │  Handler    │                    │  Handler    │     │
│  └──────┬──────┘                    └──────┬──────┘     │
│         │                                   │            │
│         └──────────────┬────────────────────┘            │
│                        │                                 │
│                 ┌──────▼──────┐                          │
│                 │  WolfSentry  │                          │
│                 │   Firewall   │                          │
│                 └──────┬──────┘                          │
│                        │                                 │
│                 ┌──────▼──────┐                          │
│                 │   IP Stack   │                          │
│                 │   (TUN/TAP)  │                          │
│                 └─────────────┘                          │
│                                                          │
└─────────────────────────────────────────────────────────┘

Common Development Tasks​

Adding a New API Endpoint​

  1. Define the endpoint in API specification
  2. Implement the handler in C
  3. Add authentication and authorization checks
  4. Write unit tests for the endpoint
  5. Document in API reference
  6. Update OpenAPI spec (if applicable)

See REST API Guide for details.

Implementing Custom Authentication​

  1. Create auth module following plugin architecture
  2. Implement auth interface (validate, authorize)
  3. Register module in configuration
  4. Test with real clients
  5. Document configuration

See Custom Authentication for examples.

Contributing Code​

  1. Fork the repository on GitHub
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Write code following coding standards
  4. Add tests for new functionality
  5. Update documentation as needed
  6. Submit pull request with clear description

See Contributing Guide for details.

Technology Stack​

ComponentTechnology
LanguageC23 (ISO/IEC 9899:2023)
TLS/CryptoWolfSSL 5.6.0+
Event Looplibev
FirewallWolfSentry
Build SystemCMake 3.20+
TestingCheck, CTest
DocumentationDoxygen

Coding Standards​

C23 Best Practices​

  • Use nullptr instead of NULL
  • Use bool, true, false from <stdbool.h>
  • Use static_assert for compile-time checks
  • Use _Generic for type-generic functions
  • Follow MISRA-C guidelines where applicable

Code Style​

// Function naming: snake_case
int wolfguard_auth_validate(const char *username, const char *password);

// Constants: UPPER_SNAKE_CASE
#define WOLFGUARD_MAX_USERS 1000

// Structs: snake_case with _t suffix
typedef struct wolfguard_config_t {
    char *server_name;
    uint16_t port;
    bool tls13_only;
} wolfguard_config_t;

// Error handling: always check return values
int result = wolfguard_init();
if (result != WOLFGUARD_SUCCESS) {
    log_error("Initialization failed: %s", wolfguard_strerror(result));
    return result;
}

Security Considerations​

  1. Input validation - Validate all external input
  2. Buffer safety - Use safe string functions
  3. Constant-time comparisons - For cryptographic operations
  4. Secure memory - Zero sensitive data after use
  5. Least privilege - Drop privileges as early as possible

API Design Principles​

  1. RESTful - Follow REST conventions
  2. Versioned - API version in URL (/api/v1/)
  3. Authenticated - All endpoints require authentication
  4. JSON - Use JSON for request/response bodies
  5. Idempotent - GET/PUT/DELETE operations are idempotent
  6. Documented - Complete OpenAPI specification

Performance Optimization​

Connection Handling​

  • Zero-copy where possible
  • Connection pooling for database
  • Async I/O with libev event loop
  • Caching for frequently accessed data

Memory Management​

  • Arena allocators for temporary allocations
  • Object pools for frequently created/destroyed objects
  • Reference counting for shared resources
  • Valgrind testing to detect leaks

Debugging Tools​

ToolPurpose
GDBInteractive debugging
ValgrindMemory leak detection
AddressSanitizerMemory error detection
straceSystem call tracing
tcpdump/WiresharkNetwork protocol analysis
perfPerformance profiling

Resources​

Ready to start developing? Check out the Architecture Overview or dive into Code Examples