Skip to content

Latest commit

 

History

History
297 lines (238 loc) · 17.9 KB

sec-design.md

File metadata and controls

297 lines (238 loc) · 17.9 KB

Okay, let's create a design document for the Hyper project, focusing on aspects relevant to threat modeling.

BUSINESS POSTURE

Hyper is a low-level HTTP library, providing both client and server implementations. It's designed for performance and correctness, forming a foundational component for many Rust-based network applications and frameworks. Given its low-level nature and widespread use, the primary business goals and priorities are:

  • Reliability: Hyper must be stable and dependable. Bugs or vulnerabilities can have cascading effects on applications built upon it.
  • Performance: As a low-level library, speed and efficiency are paramount. Performance regressions can significantly impact the performance of dependent applications.
  • Correctness: Hyper must adhere strictly to HTTP specifications (RFCs) to ensure interoperability and prevent protocol-level vulnerabilities.
  • Security: Given its role in handling network traffic, security is critical. Vulnerabilities in Hyper could expose many applications to attacks.
  • Maintainability: The project needs to be maintainable to ensure long term support, security and new features.

Most important business risks that need to be addressed:

  • Denial of Service (DoS): Vulnerabilities that allow an attacker to crash or significantly slow down applications using Hyper.
  • Remote Code Execution (RCE): Vulnerabilities that allow an attacker to execute arbitrary code on systems using Hyper.
  • Information Disclosure: Vulnerabilities that leak sensitive information, such as headers, cookies, or request/response bodies.
  • Protocol-Level Attacks: Exploits targeting HTTP protocol weaknesses, such as HTTP request smuggling or response splitting.
  • Supply Chain Attacks: Compromise of Hyper's dependencies or build process, leading to the introduction of malicious code.

SECURITY POSTURE

Existing security controls and accepted risks (based on the GitHub repository and common practices):

  • security control: Fuzzing: Hyper uses fuzzing (via cargo fuzz) to test for unexpected behavior and potential vulnerabilities. (Found in the repository's fuzzing directory and documentation).
  • security control: Continuous Integration (CI): Hyper has CI configured (GitHub Actions) to run tests and checks on every commit and pull request. (Visible in the .github/workflows directory).
  • security control: Code Reviews: All changes go through code review, providing a manual check for potential security issues. (Implicit in the pull request process).
  • security control: Static Analysis: The project likely uses Rust's built-in compiler checks and potentially tools like Clippy for static analysis. (Standard Rust practice).
  • security control: Dependency Management: Cargo (Rust's package manager) manages dependencies, providing some level of control over the supply chain.
  • security control: Security Policy: Hyper has a security policy (SECURITY.md) that describes how to report vulnerabilities.
  • accepted risk: Complexity: As a low-level HTTP implementation, Hyper is inherently complex, increasing the risk of subtle bugs.
  • accepted risk: Performance Trade-offs: The focus on performance might lead to design choices that are more complex and potentially less secure than simpler alternatives.
  • accepted risk: Reliance on Unsafe Code: Hyper, for performance reasons, might use unsafe Rust code, which bypasses some of Rust's safety guarantees. This requires extra scrutiny.

Recommended security controls (high priority):

  • security control: Regular Security Audits: Conduct periodic, independent security audits of the codebase.
  • security control: Enhanced Fuzzing: Expand fuzzing coverage to include more protocol features and edge cases. Consider using more advanced fuzzing techniques.
  • security control: Supply Chain Security Measures: Implement measures to verify the integrity of dependencies, such as using cargo-crev for trust reviews or reproducible builds.
  • security control: Static Application Security Testing (SAST): Integrate a dedicated SAST tool into the CI pipeline to automatically detect potential vulnerabilities.
  • security control: Dynamic Application Security Testing (DAST): While harder to apply to a library, consider using DAST-like techniques to test the running library against known attack patterns.

Security Requirements:

  • Authentication: Hyper itself doesn't handle application-level authentication (e.g., user logins). It should correctly handle HTTP authentication mechanisms (e.g., Basic, Bearer) as defined in the relevant RFCs.
  • Authorization: Hyper is not responsible for authorization decisions. It should correctly transmit authorization-related headers (e.g., Authorization).
  • Input Validation: Hyper must rigorously validate all inputs, including headers, request bodies, and URI components, to prevent protocol-level attacks. This is a critical area for security.
  • Cryptography: Hyper should correctly implement TLS/SSL for secure communication (HTTPS). It should use well-vetted cryptographic libraries and avoid implementing its own cryptography.
  • Output Encoding: Hyper should not perform output encoding.
  • Error Handling: Hyper should handle errors in a way that does not expose sensitive information or create vulnerabilities.

DESIGN

C4 CONTEXT

graph LR
    User(("User\n(Web Browser, Mobile App, etc.)")) --> Hyper
    Hyper --> "External Service\n(e.g., Web Server)"
    Hyper -.-> "Operating System\n(Network Stack)"
Loading

Element descriptions:

  • Element:

    • Name: User
    • Type: External Entity (Person)
    • Description: Represents any entity making HTTP requests or receiving HTTP responses via Hyper. This could be a web browser, a mobile application, another server, etc.
    • Responsibilities: Initiates HTTP requests, processes HTTP responses.
    • Security controls: Relies on Hyper for secure communication (TLS/SSL), proper handling of HTTP headers, and protection against protocol-level attacks.

  • Element:

    • Name: Hyper
    • Type: System
    • Description: The Hyper HTTP library, providing client and server implementations.
    • Responsibilities: Parsing and generating HTTP messages, managing connections, handling TLS/SSL, implementing HTTP protocol logic.
    • Security controls: Fuzzing, CI, Code Reviews, Static Analysis, Dependency Management, Security Policy.

  • Element:

    • Name: External Service
    • Type: External System
    • Description: Any external system that Hyper communicates with, such as a web server or another service.
    • Responsibilities: Responds to HTTP requests (if a server) or processes HTTP responses (if a client).
    • Security controls: Relies on its own security measures; Hyper should not introduce vulnerabilities that compromise the external service.

  • Element:

    • Name: Operating System
    • Type: External System
    • Description: The underlying operating system providing network stack functionality.
    • Responsibilities: Provides low-level network I/O, socket management.
    • Security controls: Relies on OS-level security features; Hyper should not bypass or compromise OS security.

C4 CONTAINER

Since Hyper is a library, the "containers" are more conceptual than deployable units. We'll represent the major components within Hyper.

graph LR
    User(("User\n(Web Browser, Mobile App, etc.)")) --> Client
    User(("User\n(Web Browser, Mobile App, etc.)")) <-- Server
    Client --> "HTTP/1.1\nCodec"
    Client --> "HTTP/2\nCodec"
    Client --> "Connection\nPool"
    Client --> "TLS\n(rustls/openssl)"
    "HTTP/1.1\nCodec" --> "Network\nI/O"
    "HTTP/2\nCodec" --> "Network\nI/O"
    "Connection\nPool" --> "Network\nI/O"
    Server --> "HTTP/1.1\nCodec"
    Server --> "HTTP/2\nCodec"
    Server --> "Connection\nManagement"
    Server --> "TLS\n(rustls/openssl)"
    "HTTP/1.1\nCodec" --> "Network\nI/O"
    "HTTP/2\nCodec" --> "Network\nI/O"
    "Connection\nManagement" --> "Network\nI/O"
    "Network\nI/O" --> "Operating System\n(Network Stack)"
Loading

Element descriptions:

  • Element:

    • Name: Client
    • Type: Component
    • Description: The Hyper client component, used for making HTTP requests.
    • Responsibilities: Constructing requests, sending requests, receiving responses, managing connections.
    • Security controls: Input validation, proper handling of headers, TLS/SSL configuration.

  • Element:

    • Name: Server
    • Type: Component
    • Description: The Hyper server component, used for handling incoming HTTP requests.
    • Responsibilities: Receiving requests, parsing requests, sending responses, managing connections.
    • Security controls: Input validation, proper handling of headers, TLS/SSL configuration, protection against DoS attacks.

  • Element:

    • Name: HTTP/1.1 Codec
    • Type: Component
    • Description: Handles encoding and decoding of HTTP/1.1 messages.
    • Responsibilities: Parsing and serializing HTTP/1.1 requests and responses.
    • Security controls: Robust parsing to prevent protocol-level attacks (e.g., request smuggling, response splitting).

  • Element:

    • Name: HTTP/2 Codec
    • Type: Component
    • Description: Handles encoding and decoding of HTTP/2 messages.
    • Responsibilities: Parsing and serializing HTTP/2 frames.
    • Security controls: Robust parsing to prevent HTTP/2-specific attacks.

  • Element:

    • Name: Connection Pool (Client)
    • Type: Component
    • Description: Manages a pool of reusable connections for the client.
    • Responsibilities: Creating, reusing, and closing connections.
    • Security controls: Properly closing connections, preventing connection leaks, enforcing connection limits.

  • Element:

    • Name: Connection Management (Server)
    • Type: Component
    • Description: Manages incoming connections for the server.
    • Responsibilities: Accepting connections, managing connection lifecycle.
    • Security controls: Enforcing connection limits, handling connection errors gracefully, preventing DoS attacks.

  • Element:

    • Name: TLS (rustls/openssl)
    • Type: Library
    • Description: Provides TLS/SSL implementation (likely using rustls or openssl).
    • Responsibilities: Establishing secure connections, encrypting and decrypting data.
    • Security controls: Using well-vetted cryptographic libraries, proper TLS configuration, certificate validation.

  • Element:

    • Name: Network I/O
    • Type: Component
    • Description: Handles low-level network input/output.
    • Responsibilities: Reading and writing data to sockets.
    • Security controls: Proper error handling, avoiding buffer overflows.

  • Element:

    • Name: User
    • Type: External Entity (Person)
    • Description: Represents any entity making HTTP requests or receiving HTTP responses via Hyper. This could be a web browser, a mobile application, another server, etc.
    • Responsibilities: Initiates HTTP requests, processes HTTP responses.
    • Security controls: Relies on Hyper for secure communication (TLS/SSL), proper handling of HTTP headers, and protection against protocol-level attacks.

  • Element:

    • Name: Operating System
    • Type: External System
    • Description: The underlying operating system providing network stack functionality.
    • Responsibilities: Provides low-level network I/O, socket management.
    • Security controls: Relies on OS-level security features; Hyper should not bypass or compromise OS security.

DEPLOYMENT

Hyper is a library, not a standalone application. Therefore, deployment is about how it's integrated into other projects.

Possible deployment solutions:

  1. Direct Dependency: The most common scenario. Applications using Hyper include it as a direct dependency via Cargo. The library code is compiled directly into the application's binary.
  2. Indirect Dependency: Hyper may be included as a transitive dependency of other libraries or frameworks.
  3. Dynamic Linking (Less Common): While less common for Rust libraries, it's theoretically possible to link Hyper dynamically.

Chosen solution (most common): Direct Dependency

graph LR
    Application --> "Hyper (Library)"
    "Hyper (Library)" --> "rustls/openssl\n(Library)"
    "Hyper (Library)" --> "Operating System"
Loading

Element descriptions:

  • Element:

    • Name: Application
    • Type: Application
    • Description: The application that uses Hyper as a library.
    • Responsibilities: Implements the application's specific logic, using Hyper for HTTP communication.
    • Security controls: Depends on the application's own security measures, as well as Hyper's security.

  • Element:

    • Name: Hyper (Library)
    • Type: Library
    • Description: The Hyper library, compiled into the application.
    • Responsibilities: Provides HTTP client and server functionality.
    • Security controls: Fuzzing, CI, Code Reviews, Static Analysis, Dependency Management, Security Policy.

  • Element:

    • Name: rustls/openssl (Library)
    • Type: Library
    • Description: The TLS/SSL library used by Hyper.
    • Responsibilities: Provides cryptographic functions for secure communication.
    • Security controls: Relies on the security of the chosen TLS library (rustls or openssl).

  • Element:

    • Name: Operating System
    • Type: External System
    • Description: The underlying operating system.
    • Responsibilities: Provides network stack, process management, etc.
    • Security controls: Relies on OS-level security.

BUILD

Hyper uses Cargo, Rust's build system and package manager, along with GitHub Actions for CI/CD.

graph LR
    Developer --> "Source Code\n(GitHub)"
    "Source Code\n(GitHub)" --> "GitHub Actions\n(CI/CD)"
    "GitHub Actions\n(CI/CD)" --> "Cargo Build"
    "Cargo Build" --> "Tests\n(Unit, Integration, Fuzzing)"
    "Cargo Build" --> "Static Analysis\n(Clippy)"
    "Tests\n(Unit, Integration, Fuzzing)" -- Success --> "Crates.io\n(Package Registry)"
    "Static Analysis\n(Clippy)" -- Success --> "Crates.io\n(Package Registry)"
    "GitHub Actions\n(CI/CD)" -- Failure --> Developer
    "Tests\n(Unit, Integration, Fuzzing)" -- Failure --> Developer
    "Static Analysis\n(Clippy)" -- Failure --> Developer
Loading

Build process description:

  1. Developer: Developers write code and push changes to the GitHub repository.
  2. Source Code (GitHub): The code is hosted on GitHub.
  3. GitHub Actions (CI/CD): GitHub Actions triggers workflows on various events (push, pull request). These workflows define the build and test process.
  4. Cargo Build: The cargo build command compiles the Hyper library.
  5. Tests (Unit, Integration, Fuzzing): Cargo runs unit tests, integration tests, and fuzzing tests.
  6. Static Analysis (Clippy): Clippy (a Rust linter) performs static analysis to identify potential code quality and style issues.
  7. Crates.io (Package Registry): If all tests and checks pass, a new version of Hyper can be published to crates.io, the Rust package registry.
  8. Feedback loop: If build, tests or static analysis fails, developer is notified.

Security controls in the build process:

  • security control: CI/CD (GitHub Actions): Automates the build and test process, ensuring consistency and preventing manual errors.
  • security control: Tests: Automated tests (unit, integration, fuzzing) help catch bugs and vulnerabilities early.
  • security control: Static Analysis (Clippy): Identifies potential code quality and security issues.
  • security control: Dependency Management (Cargo): Manages dependencies and their versions, reducing the risk of using outdated or vulnerable libraries.

RISK ASSESSMENT

  • Critical Business Processes: Reliable and secure HTTP communication for applications built using Hyper. This includes both client-side (making requests) and server-side (handling requests) operations.
  • Data We Are Trying to Protect:
    • Network Traffic: The content of HTTP requests and responses, which may contain sensitive data (depending on the application using Hyper). Sensitivity: Varies greatly depending on the application. Could range from public data to highly confidential information.
    • Headers and Cookies: HTTP headers and cookies, which may contain authentication tokens, session identifiers, or other sensitive information. Sensitivity: Potentially high, as these can be used for session hijacking or impersonation.
    • Internal Library State: While not directly exposed, vulnerabilities in Hyper could potentially allow attackers to access or modify internal library state. Sensitivity: High, as this could lead to arbitrary code execution.

QUESTIONS & ASSUMPTIONS

  • Questions:

    • What specific TLS/SSL libraries are used in different build configurations (rustls, openssl, etc.)? How are these libraries configured and updated?
    • What are the specific performance requirements and constraints for Hyper? This can help understand the trade-offs made in the design.
    • What is the expected threat model for applications using Hyper? Are there specific types of attacks that are of particular concern?
    • Are there any plans to integrate more advanced security testing tools (e.g., SAST, DAST) into the CI pipeline?
    • How is unsafe code usage reviewed and minimized within Hyper?

  • Assumptions:

    • BUSINESS POSTURE: We assume that the Hyper project prioritizes security alongside performance and correctness.
    • SECURITY POSTURE: We assume that the existing security controls (fuzzing, CI, code reviews) are implemented effectively. We assume that developers follow secure coding practices.
    • DESIGN: We assume that the major components of Hyper are accurately represented in the C4 diagrams. We assume that the build process described is accurate and complete. We assume that Hyper relies on well-established and actively maintained TLS/SSL libraries.