{"id":13546058,"url":"https://github.com/aws/http-desync-guardian","last_synced_at":"2025-04-05T05:07:37.974Z","repository":{"id":55421319,"uuid":"283044183","full_name":"aws/http-desync-guardian","owner":"aws","description":"Analyze HTTP requests to minimize risks of HTTP Desync attacks (precursor for HTTP request smuggling/splitting). ","archived":false,"fork":false,"pushed_at":"2020-12-31T18:39:51.000Z","size":468,"stargazers_count":264,"open_issues_count":1,"forks_count":19,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-03-29T04:09:45.408Z","etag":null,"topics":["http-desync","http-request-smuggling","http-smuggling"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-27T23:42:40.000Z","updated_at":"2025-03-18T23:09:48.000Z","dependencies_parsed_at":"2022-08-15T00:00:35.592Z","dependency_job_id":null,"html_url":"https://github.com/aws/http-desync-guardian","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fhttp-desync-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fhttp-desync-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fhttp-desync-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fhttp-desync-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/http-desync-guardian/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289428,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http-desync","http-request-smuggling","http-smuggling"],"created_at":"2024-08-01T12:00:30.788Z","updated_at":"2025-04-05T05:07:37.958Z","avatar_url":"https://github.com/aws.png","language":"Rust","funding_links":[],"categories":["Web and Cloud Security","Rust (42)","Rust","Tools"],"sub_categories":["Secure Frameworks"],"readme":"\u003cimg src=\"docs/http-desync-guardian-logo.png\" width=\"200\"\u003e\n\n[![Apache 2 License](https://img.shields.io/github/license/awslabs/s2n.svg)](http://aws.amazon.com/apache-2-0/)\n[![Crate](https://img.shields.io/crates/v/http_desync_guardian.svg)](https://crates.io/crates/http_desync_guardian)\n![Clippy/Fmt](https://github.com/aws/http-desync-guardian/workflows/Clippy/Fmt/badge.svg)\n![Tests](https://github.com/aws/http-desync-guardian/workflows/Tests/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/aws/http-desync-guardian/badge.svg?branch=master)](https://coveralls.io/github/aws/http-desync-guardian?branch=master)\n\n\n\nOverview\n========\n\n`HTTP/1.1` went through a long evolution since 1991 to 2014:\n\n* [HTTP/0.9](https://www.w3.org/Protocols/HTTP/AsImplemented.html) – 1991\n* [HTTP/1.0](https://tools.ietf.org/html/rfc1945) – 1996\n* HTTP/1.1\n  * [RFC 2068](https://tools.ietf.org/html/rfc2068) – 1997\n  * [RFC 2616](https://tools.ietf.org/html/rfc2616) - 1999\n  * [RFC 7230](https://tools.ietf.org/html/rfc7230) - 2014\n\nThis means there is a variety of servers and clients, which might have different views on request boundaries, creating opportunities for desynchronization attacks (a.k.a. HTTP Desync). \t \n  \nIt might seem simple to follow the latest RFC recommendations. However, for large scale systems that have been there for a while, it may come with unacceptable availability impact.\t \n  \n`http_desync_guardian` library is designed to analyze HTTP requests to prevent HTTP Desync attacks, balancing security and availability. \nIt classifies requests into different [categories](/docs#request-classification) and provides recommendations on how each tier should be handled.\n\nIt can be used either for raw HTTP request headers or already parsed by an HTTP engine.\nConsumers may configure logging and metrics collection.\nLogging is rate limited and all user data is obfuscated. \n\nIf you think you might have found a security impacting issue, please follow [our Security Notification Process.](#security-issue-notifications)\n\nPriorities\n=======\n\n* **Uniformity across services is key.** This means request classification, logging, and metrics must happen under the hood and with minimally available settings (e.g., such as log file destination).\n* **Focus on reviewability.** The test suite must require no knowledge about the library/programming languages but only about HTTP protocol. So it's easy to review, contribute, and re-use.\n* **Security is efficient when it's easy for users.** Our goal is to make integration of the library as simple as possible.\n* **Ultralight.** The overhead must be minimal and impose no tangible tax on request handling (see [benchmarks](./benches)).\n\nSupported HTTP versions\n======\n\nThe main focus of this library is `HTTP/1.1`. See [tests](./tests) for all covered cases. Predecessors of `HTTP/1.1` don't support connection re-use which limits opportunities for HTTP Desync,\nhowever some proxies may upgrade such requests to `HTTP/1.1` and re-use backend connections, which may allow to craft malicious `HTTP/1.0` requests. \nThat's why they are analyzed using the same criteria as `HTTP/1.1`. For other protocol versions have the following exceptions:\n\n* `HTTP/0.9` requests are never considered `Compliant`, but are classified as `Acceptable`. If any of `Content-Length`/`Transfer-Encoding` is present then it's `Ambiguous`.\n* `HTTP/1.0` - the presence of `Transfer-Encoding` makes a request `Ambiguous`.\n* `HTTP/2+` is out of scope. But if your proxy downgrades `HTTP/2` to `HTTP/1.1`, make sure the outgoing request is analyzed. \n\nSee [documentation](./docs) to learn more.\n\nUsage from C\n=====\n\nThis library is designed to be primarily used from HTTP engines written in `C/C++`.  \n\n1. Install [cbindgen](https://github.com/eqrion/cbindgen#cbindgen-----): `cargo install --force cbindgen`\n1. Generate the header file: \n   * Run `cbindgen --output http_desync_guardian.h --lang c` for C.\n   * Run `cbindgen --output http_desync_guardian.h --lang c++` for C++.\n1. Run `cargo build --release`. The binaries are in `./target/release/libhttp_desync_guardian.*` files.\n\nLearn more: [generic](./misc/demo-c) and [Nginx](./misc/demo-nginx) examples.\n\n```c\n#include \"http_desync_guardian.h\"\n\n/* \n * http_engine_request_t - already parsed by the HTTP engine \n */\nstatic int check_request(http_engine_request_t *req) {\n    http_desync_guardian_request_t guardian_request = construct_http_desync_guardian_from(req); \n    http_desync_guardian_verdict_t verdict = {0};\n\n    http_desync_guardian_analyze_request(\u0026guardian_request, \u0026verdict);\n\n    switch (verdict.tier) {\n        case REQUEST_SAFETY_TIER_COMPLIANT:\n            // The request is good. green light\n            break;\n        case REQUEST_SAFETY_TIER_ACCEPTABLE:\n            // Reject, if mode == STRICTEST\n            // Otherwise, OK\n            break;\n        case REQUEST_SAFETY_TIER_AMBIGUOUS:\n            // The request is ambiguous.\n            // Reject, if mode == STRICTEST \n            // Otherwise send it, but don't reuse both FE/BE connections.\n            break;\n        case REQUEST_SAFETY_TIER_SEVERE:\n            // Send 400 and close the FE connection.\n            break;\n        default:\n            // unreachable code\n            abort();\n    }\n}\n```\n\nUsage from Rust\n====\n\nSee [benchmarks](./benches/benchmarks.rs) as an example of usage from Rust. \n\n## Security issue notifications\n\nIf you discover a potential security issue in `http_desync_guardian` we ask that you notify\nAWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. \n\n## Security\n\nSee [CONTRIBUTING](./CONTRIBUTING.md#contributing-guidelines) for more information.\n\n## License\n\nThis project is licensed under the [Apache-2.0 License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fhttp-desync-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Fhttp-desync-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fhttp-desync-guardian/lists"}