{"id":15642116,"url":"https://github.com/wi1dcard/fingerproxy","last_synced_at":"2025-04-04T18:05:07.761Z","repository":{"id":222977552,"uuid":"758877501","full_name":"wi1dcard/fingerproxy","owner":"wi1dcard","description":"Fingerproxy is an HTTPS reverse proxy. It creates JA3, JA4, Akamai HTTP2 fingerprints, and forwards to backend via HTTP request headers.","archived":false,"fork":false,"pushed_at":"2025-03-13T09:00:52.000Z","size":5285,"stargazers_count":168,"open_issues_count":5,"forks_count":23,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T17:06:44.200Z","etag":null,"topics":["fingerprinting","http2-fingerprint","ja3","ja4","reverse-proxy","tls"],"latest_commit_sha":null,"homepage":"","language":"Go","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/wi1dcard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-17T10:47:54.000Z","updated_at":"2025-03-27T19:54:43.000Z","dependencies_parsed_at":"2024-04-28T08:29:32.910Z","dependency_job_id":"44abd9b7-a4d3-4615-95fe-c4442400e5c7","html_url":"https://github.com/wi1dcard/fingerproxy","commit_stats":{"total_commits":78,"total_committers":4,"mean_commits":19.5,"dds":0.05128205128205132,"last_synced_commit":"b23cd9be7c5d4382fb05887ca4748d8fd757e52a"},"previous_names":["wi1dcard/fingerproxy"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Ffingerproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Ffingerproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Ffingerproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Ffingerproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wi1dcard","download_url":"https://codeload.github.com/wi1dcard/fingerproxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226213,"owners_count":20904465,"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":["fingerprinting","http2-fingerprint","ja3","ja4","reverse-proxy","tls"],"created_at":"2024-10-03T11:54:37.235Z","updated_at":"2025-04-04T18:05:07.740Z","avatar_url":"https://github.com/wi1dcard.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Fingerproxy\n\nInspired by [gospider007/fp](https://github.com/gospider007/fp). Fingerproxy is an HTTPS reverse proxy. It creates JA3, JA4, Akamai HTTP2 fingerprints, and forwards to backend via HTTP request headers.\n\n```\n         HTTPS                            HTTP/1.1 or HTTP/2\nClient ---------\u003e Fingerproxy   --------------------------------------\u003e  HTTP Backend\n                 (listens :443)    | Request headers:               |   (127.0.0.1:80)\n                                   |   X-JA3-Fingerprint: abcd...   |\n                                   |   X-JA4-Fingerprint: t13d...   |\n                                   |   X-HTTP2-Fingerprint: 3:100...|\n```\n\nFingerprints can be used for bot detection, DDoS mitigation, client identification, etc. To use these fingerprints, just extract the HTTP request headers in your backend apps.\n\nFingerproxy is also a Go library, which allows users implementing their own fingerprinting algorithm.\n\n## Usage\n\n\u003e [!TIP]\n\u003e Try fingerproxy in 1 minute:\n\n1. Generate a self-signed certificate `tls.crt` and `tls.key` for testing.\n    ```bash\n    openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -days 3650 \\\n      -nodes -keyout tls.key -out tls.crt -subj \"/CN=localhost\" \\\n      -addext \"subjectAltName=DNS:localhost,DNS:*.localhost,IP:127.0.0.1\"\n    ```\n\n2. Download the [fingerproxy binary](https://github.com/wi1dcard/fingerproxy/releases) and run.\n    ```bash\n    ./fingerproxy -listen-addr :8443 -forward-url https://httpbin.org\n    ```\n    Server listens on `:8443`, forwarding requests to [httpbin](https://httpbin.org/).\n\n3. We are ready to go. Send an HTTPS request to fingerproxy:\n    ```bash\n    curl \"https://localhost:8443/anything?show_env=1\" --insecure\n    ```\n\n    You will see fingerprints in request headers:\n\n    ```yaml\n    {\n      \"headers\": {\n        # ...\n        \"X-Forwarded-Host\": \"localhost:8443\",\n        \"X-Forwarded-Port\": \"443\",\n        \"X-Forwarded-Proto\": \"https\",\n        \"X-Http2-Fingerprint\": \"3:100;4:10485760;2:0|1048510465|0|m,s,a,p\",\n        \"X-Ja3-Fingerprint\": \"0149f47eabf9a20d0893e2a44e5a6323\",\n        \"X-Ja4-Fingerprint\": \"t13d3112h2_e8f1e7e78f70_6bebaf5329ac\"\n      },\n      # ...\n    }\n    ```\n\nFor all available CLI options, see `fingerproxy --help`.\n\n## Production-Ready\n\nThe fingerproxy binary is production-ready. [Subscan.io](https://www.subscan.io/) has 12 fingerproxy instances running in the production environment, which process almost 40,000,000 requests/day on average.\n\nUnit tests, memory usage tests, E2E tests, and benchmarks have been implemented and run on GitHub Actions.\n\nAnd of course, fingerproxy follows SemVer.\n\n## Kubernetes and Prometheus Integration\n\nKubernetes liveness probe support is available since [v0.3.0](https://github.com/wi1dcard/fingerproxy/releases/tag/v0.3.0). Example:\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: fingerproxy\nspec:\n  containers:\n  - name: fingerproxy\n    image: fingerproxy\n    livenessProbe:\n      httpGet:\n        path: /\n        port: 443\n        scheme: https\n```\n\nKubernetes probes use certain User-Agent such as `kube-probe/1.26`. Therefore, those requests with the specific user-agent header can be recognized as probing requests. Instead of forwarding to the backend app, fingerproxy will simply respond with an `HTTP 200` by itself.\n\nThe default Prometheus metrics server listens on `:9035`. Once new requests come in, run `curl http://localhost:9035/` to see avaialble metrics.\n\n## Implement Your Fingerprinting Algorithm\n\nCheck out the examples [`ja3-raw`](example/ja3-raw/) or [`my-fingerprint`](example/my-fingerprint/). No code fork needed.\n\n## Chrome JA3 Fingerprints Change Every Time\n\nYes, it is an known issue of the original JA3 implementation. See [Google Chrome TLS extension permutation](https://github.com/net4people/bbs/issues/220). Sorting the TLS extension is one method to avoid the affect of this feature. Here is an example [ja3-sorted-extensions](example/ja3-sorted-extensions/).\n\n## Use as a Library\n\nFingerproxy is degigned to be highly customizable. It is separated into serveral packages. You can find all packages in the [`pkg`](pkg/) dir and use them to build your own fingerprinting server.\n\nHere is an example [`echo-server`](example/echo-server/). Instead of forwarding HTTP requests, it simply responds back to client with the fingerprints.\n\n## Similar Projects\n\n- [gospider007/fp](https://github.com/gospider007/fp)\n\n  Great implementation based on golang net stack, works nice with golang HTTP handler. Fingerproxy rewrites TLS ClientHello capturing according to it.\n\n  Why I didn't use it?\n\n  - The JA3 and JA4 implementations contain bugs. For example,\n    - In [fp.go](https://github.com/gospider007/ja3/blob/a58a93a771b99909e859ead9a9492015dd916947/fp.go#L337), `_` should be used instead of `,` as the separator of extensions and signature algorithms.\n    - In [fp.go](https://github.com/gospider007/ja3/blob/a58a93a771b99909e859ead9a9492015dd916947/fp.go#L80), the protocol version in ClientHello handshake should be used for JA3.\n    - In [ja3.go](https://github.com/gospider007/ja3/blob/a58a93a771b99909e859ead9a9492015dd916947/ja3.go#L769), `;` should be used instead of `,` as the parameters separator in HTTP2 settings frame.\n    - Priority frame used in HTTP2 fingerprinting has not implemented yet.\n  - KISS\n    - JA4H can be calculated in backend applications. Do not do it in the reverse proxy.\n    - Complex design, unused methods, and copy-pastes from unknown source.\n\n- [sleeyax/ja3rp](https://github.com/sleeyax/ja3rp)\n\n  Discontinued.\n\n- [h3adex/guardgress](https://github.com/h3adex/guardgress)\n\n  Relies on [gospider007/fp](https://github.com/gospider007/fp).\n\n- [wwhtrbbtt/TrackMe](https://github.com/wwhtrbbtt/TrackMe)\n\n  An HTTPS echo server that responds the fingerprints.\n\n  Why I didn't use it?\n\n  - It is not designed for forwarding the requests.\n  - Bugs too. In [ja4.go](https://github.com/wwhtrbbtt/TrackMe/blob/41b7933efe9ea364ade88ac6ea0e79a7b0203227/ja4.go#L85), the padding extension (21) somehow has preserved. Therefore there would be two duplicated `21` extension which is incorrect.\n\n## Useful Websites\n\n- \u003chttps://browserleaks.com/tls\u003e\n\n  JA3 and JA3 with sorted TLS extensions.\n\n- \u003chttps://scrapfly.io/web-scraping-tools/ja3-fingerprint\u003e\n\n  JA3 and HTTP2 fingerprint. As per the comment from Scrapfly team member, Scrapfly uses an improved variant of JA3 implementation. It makes more sense in real life use cases, however, please notice that these JA3 results are not comparable with others. For more information, please read issue [#14](https://github.com/wi1dcard/fingerproxy/issues/14).\n\n- \u003chttps://tls.peet.ws/\u003e\n\n  Public deployment of [wwhtrbbtt/TrackMe](https://github.com/wwhtrbbtt/TrackMe); JA4 result might be incorrect (see above).\n\n## References\n\n- JA3 fingerprint: \u003chttps://github.com/salesforce/ja3\u003e\n- JA4 fingerprint: \u003chttps://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md\u003e\n- Akamai HTTP2 fingerprinting: \u003chttps://www.blackhat.com/docs/eu-17/materials/eu-17-Shuster-Passive-Fingerprinting-Of-HTTP2-Clients-wp.pdf\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwi1dcard%2Ffingerproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwi1dcard%2Ffingerproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwi1dcard%2Ffingerproxy/lists"}