{"id":13775788,"url":"https://github.com/johndoe31415/ratched","last_synced_at":"2025-12-30T01:50:08.151Z","repository":{"id":74119746,"uuid":"112028206","full_name":"johndoe31415/ratched","owner":"johndoe31415","description":"Ratched is a transparent Man-in-the-Middle TLS proxy intended for penetration testing","archived":false,"fork":false,"pushed_at":"2021-07-19T22:03:33.000Z","size":254,"stargazers_count":33,"open_issues_count":3,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-03T17:12:14.713Z","etag":null,"topics":["attack","intercept","mitm","pentest","security","ssl","tls"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johndoe31415.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-11-25T19:13:51.000Z","updated_at":"2024-03-28T21:07:31.000Z","dependencies_parsed_at":"2024-01-07T22:56:11.733Z","dependency_job_id":null,"html_url":"https://github.com/johndoe31415/ratched","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/johndoe31415%2Fratched","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndoe31415%2Fratched/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndoe31415%2Fratched/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johndoe31415%2Fratched/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johndoe31415","download_url":"https://codeload.github.com/johndoe31415/ratched/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225027562,"owners_count":17409460,"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":["attack","intercept","mitm","pentest","security","ssl","tls"],"created_at":"2024-08-03T17:01:49.983Z","updated_at":"2025-12-30T01:50:08.124Z","avatar_url":"https://github.com/johndoe31415.png","language":"C","funding_links":[],"categories":["\u003ca id=\"d03d494700077f6a65092985c06bf8e8\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"0ff94312f3ab4898f5996725133ea9d1\"\u003e\u003c/a\u003e未分类"],"readme":"# ratched\n[![Build Status](https://travis-ci.com/johndoe31415/ratched.svg?branch=master)](https://travis-ci.com/johndoe31415/ratched)\n\nratched is a Man-in-the-Middle (MitM) proxy that specifically intercepts TLS\nconnections. It is intended to be used in conjunction with the Linux iptabes\nREDIRECT target; all connections that should be intercepted can be redirected\nto the local ratched port. Through the SO_ORIGINAL_DST sockopt, ratched can\ndetermine the intended destination (before iptables packet mangling) and tries\nto establish a connection to the original target.\n\nThe thing that sets it apart from other MitM software is the following:\n\n  1. ratched does not intercept traffic indiscriminately. In particular, it\n     first waits for the TLS client to send its ClientHello so that ratched can\n     parse it and decide by the Server Name Indication TLS extension (SNI) if\n     the target should be intercepted or not. This is particularly useful when\n     you have virtual hosting, but only want to intercept connections to a\n     specific hostname.\n\n  2. ratched is not intended to only sniff passwords, but primarily dumps the\n     traffic into a PCAPNG file. The PCAPNG file format was chosen because it\n     allows for annotation of connections with comments (in particular, which\n     hostname was indicated in the SNI extension) and also allows name resolution\n     information to be embedded in the capture file (again, to map the target IP\n     address to the SNI extension's hostname)\n\n  3. ratched has individual configuration for each intercepted SNI, including\n     supported groups (formerly known as \"supported elliptic curves\"), cipher\n     suites and specific TLS versions on client and server side, and allows for\n     specifying custom certificates/keys for different intercepted hosts.\n\n  4. ratched provides extensive support for client certificates and also offers\n     automatic forging for client certificates as well (similar to forged\n     server certificates in the other direction).\n\n  5. ratched supports OCSP stapling and can automatically forge positive OCSP\n     responses when a client sends a status request TLS extension.\n\n# Setup\nOnce ratched is listening on the routing machine (in the example, on port\n9999), simply add an iptables entry that specifies what traffic you want to\ncapture. For example, to intercept everything from 192.168.1.7 that tries to\nreach port 443, use:\n\n```\n# iptables -t nat -A PREROUTING -p tcp -s 192.168.1.7 --dport 443 -j REDIRECT --to-ports 9999\n```\n\nIn order to intercept everything that goes to 443, simply do:\n\n```\n# iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-ports 9999\n```\n\nIf you're acting as a router and want to intercept locally incoming traffic,\nuse the DNAT target instead of REDIRECT, such as:\n\n```\n# iptables -t nat -A PREROUTING -i eth1 -p tcp --dport 443 -j DNAT --to 192.168.123.1:9999\n```\n\nHere, eth1 is the interface you're intercepting traffing at and 192.168.123.1\nis the local interface IP address.\n\n# Usage\nThe help page should be pretty self-explanatory:\n\n[//]: # (Begin of help page -- auto-generated, do not edit!)\n\n```\nusage: ratched [-c path] [-f hostname:port] [--single-shot] [--dump-certs]\n               [--keyspec keyspec] [--initial-read-timeout secs]\n               [--mark-forged-certificates] [--no-recalculate-keyids]\n               [--daemonize] [--logfile file] [--flush-logs] [--crl-uri uri]\n               [--ocsp-uri uri] [--write-memdumps-into-files]\n               [--use-ipv6-encapsulation] [-l hostname:port]\n               [-d key=value[,key=value,...]] [-i hostname[,key=value,...]]\n               [--pcap-comment comment] [-o filename] [-v]\n\nratched - TLS connection router that performs a man-in-the-middle attack\n\noptional arguments:\n  -c path, --config-dir path\n                        Configuration directory where the default root CA\n                        certificate, CA keypair and server keypair are stored.\n                        Defaults to ~/.config/ratched\n  -f hostname:port, --local-fwd hostname:port\n                        When local connection to listening port is made, the\n                        connection is discarded by default. Specifying this\n                        option makes ratched forward to the given\n                        hostname/port combination instead. Useful for testing\n                        the proxy without the iptables REDIRECT.\n  --single-shot         Only handle a single connection and terminate directly\n                        after. Useful for debugging purposes.\n  --dump-certs          Print created certificates for each intercepted\n                        connection in the log file. Note that in many cases\n                        you will also need to increase the log level to at\n                        least DEBUG in order to see certificates.\n  --keyspec keyspec     Specification for the private keys that should be\n                        used. Can be either in the form \"rsa:bitlen\" or\n                        \"ecc:curvename\". Valid choices, therefore, would be,\n                        for example, \"rsa:1024\" or \"ecc:secp256r1\". Defaults\n                        to rsa:2048\n  --initial-read-timeout secs\n                        Specifies the amount of time in seconds (as a floating\n                        point number) that ratched waits for the client to\n                        provide its ClientHello before giving up. The default\n                        is 1.0 secs.\n  --mark-forged-certificates\n                        Include an OU=ratched entry to the subjects of all\n                        created certificates (including dynamically forged\n                        client certificates) for easy debugging.\n  --no-recalculate-keyids\n                        When forging client certificates, by default the\n                        subject and authority key identifiers are removed and\n                        recreated to fit the actually used key ids. With this\n                        option, they're used as-is (i.e., the key identifier\n                        metadata will not fit the actually used keys). This\n                        option might expose bugs in certain frameworks which\n                        regard these identifiers as trusted information.\n  --daemonize           Do not run in foreground mode, but in the background\n                        as a daemon.\n  --logfile file        Instead of logging to stderr, redirect logs to given\n                        file.\n  --flush-logs          Flush logfile after each call to logmsg(). Decreases\n                        performance, but gives line-buffered logs.\n  --crl-uri uri         Encode the given URI into the CRL Distribution Point\n                        X.509 extension of server certificates.\n  --ocsp-uri uri        Encode the given URI into the Authority Info Access\n                        X.509 extension of server certificates as the OCSP\n                        responder URI.\n  --write-memdumps-into-files\n                        When dumping a piece of memory in the log, also output\n                        its binary equivalent into a file called\n                        hexdump_####.bin, where #### is an ascending number.\n                        Useful for debugging of internal data structures.\n  --use-ipv6-encapsulation\n                        For writing the PCAPNG file format, usually IPv4 is\n                        emulated. This has the drawback that when one IPv4\n                        endpoint serves multiple servers via the TLS Server\n                        Name Indication extension, they cannot be\n                        differentiated by their hostname. With this parameter,\n                        ratched wraps the packets in IPv4-in-IPv6 emulation\n                        and assigns different IPv6 addresses for different\n                        server names, thus enabling accurate name resolution.\n  -l hostname:port, --listen hostname:port\n                        Specify the address and port that ratched is listening\n                        on. Defaults to 127.0.0.1:9999.\n  -d key=value[,key=value,...], --defaults key=value[,key=value,...]\n                        Specify the server and client connection parameters\n                        for all hosts that are not explicitly listed via a\n                        --intercept option. Arguments are given in a key=value\n                        fashion; valid arguments are shown below.\n  -i hostname[,key=value,...], --intercept hostname[,key=value,...]\n                        Intercept only a specific host name, as indicated by\n                        the Server Name Indication inside the ClientHello. Can\n                        be specified multiple times to include interception or\n                        more than one host. Additional arguments can be\n                        specified in a key=value fashion to further define\n                        interception parameters for that particular host.\n  --pcap-comment comment\n                        Store a particular piece of information inside the\n                        PCAPNG header as a comment.\n  -o filename, --outfile filename\n                        Specifies the PCAPNG file that the intercepted traffic\n                        is written to. Mandatory argument.\n  -v, --verbose         Increase logging verbosity.\n\nThe arguments which are valid for the --intercept argument are as follows:\n  intercept=[opportunistic|mandatory|forward|reject]\n                        Specifies the mode that ratched should act in for\n                        this particular connection. Opportunistic TLS\n                        interception is the default; it means that TLS\n                        interception is tried first. Should it fail, however\n                        (because someone tries to send non-TLS traffic), it\n                        falls back to 'forward' mode (i.e., forwarding all\n                        data unmodified). Mandatory TLS interception means\n                        that if no TLS interception is possible, the\n                        connection is terminated. 'forward', as explained,\n                        simply forwards everything unmodified. 'reject'\n                        closes the connection altogether, regardless of the\n                        type of seen traffic.\n  s_tlsversions=versions\n                        Colon-separated string that specifies the acceptable\n                        TLS version for the ratched server component. Valid\n                        elements are ssl2, ssl3, tls10, tls11, tls12, tls13.\n                        Defaults to tls10:tls11:tls12.\n  s_reqclientcert=bool  Ask all connecting clients to the server side of the\n                        TLS proxy for a client certificate. If not\n                        replacement certificate (at least certfile and\n                        keyfile) is given, forge all metadata of the incoming\n                        certificate. If a certfile/keyfile is given, this\n                        option is implied.\n  s_send_rot=bool       By default, the ratched TLS server does not include\n                        its own root of trust (RoT) CA certificate in the\n                        server certificates list. With this option, it is\n                        added to the certificates sent to its peer.\n  s_certfile=filename   Specifies an X.509 certificate in PEM format that\n                        should be used by ratched as the server certificate.\n                        By default, this certificate is automatically\n                        generated. Must be used in conjunction with\n                        s_keyfile.\n  s_keyfile=filename    Specifies the private key for the given server\n                        certificate, in PEM format.\n  s_chainfile=filename  Specifies the X.509 certificate chain that is to be\n                        sent to the client, in PEM format.\n  s_cacert=filename     The X.509 CA certificate that issues server\n                        certificates, in PEM format.\n  s_cakey=filename      The X.509 CA certificate key that signs server\n                        certificates, in PEM format.\n  s_ciphers=ciphers     The cipher suite string that the ratched TLS server\n                        uses.\n  s_groups=groups       The key agreement 'supported groups' string (formerly\n                        known as 'elliptic curves') that the ratched TLS\n                        server uses.\n  s_sigalgs=algs        The key agreement 'signature algorithms' string which\n                        the ratched TLS server uses.\n  s_ocsp=bool           Respond to clients requesting an OCSP status request\n                        by sending an OCSP ticket as a response. Enabled by\n                        default.\n  c_tlsversions=versions\n                        Colon-separated string that specifies the acceptable\n                        TLS version for the ratched client component. Valid\n                        elements are ssl2, ssl3, tls10, tls11, tls12, tls13.\n                        Defaults to tls10:tls11:tls12.\n  c_certfile=filename   Specifies an X.509 certificate in PEM format that\n                        should be used by ratched as a client certificate. It\n                        will only be used when the connecting client also\n                        provided a client certificate. Must be used in\n                        conjunction with c_keyfile.\n  c_keyfile=filename    The private key for the given client certificate, in\n                        PEM format.\n  c_chainfile=filename  The X.509 certificate chain that is to be sent to the\n                        server, in PEM format.\n  c_ciphers=ciphers     The cipher suite string that the ratched TLS client\n                        uses.\n  c_groups=groups       The key agreement 'supported groups' string (formerly\n                        known as 'elliptic curves') that the ratched TLS\n                        client uses.\n  c_sigalgs=algs        The key agreement 'signature algorithms' string which\n                        the ratched TLS client uses.\n\nexamples:\n    $ ratched -o output.pcapng\n      Open up local port 9999 and listen for incoming connections, intercept\n      all TLS traffic and write output into given capture file.\n\n    $ ratched -f google.com:443 -o output.pcapng\n      Same as before, but redirect all traffic of which the destination cannot\n      be determined (e.g., local connections to port 9999) to google.com on\n      port 443.\n\n    $ ratched -vvv --dump-certs -o output.pcapng\n      Be much more verbose during interception and also print out forged\n      certificates in the log.\n\n    $ ratched --defaults intercept=forward -intercept --intercept www.johannes-bauer.com -o output.pcapng\n      Do not generally intercept connections (but rather forward all traffic\n      unmodified) except for connections with Server Name Indication\n      www.johannes-bauer.com, on which interception is performed.\n\n    $ ratched --intercept www.johannes-bauer.com,s_reqclientcert=true -o output.pcapng\n      Generally do not request client certificates from connecting peers\n      except for connections with Server Name Indication www.johannes-\n      bauer.com, where clients are sent a CertificateRequest TLS message. If\n      clients do not provide a client certificate, just use regular TLS\n      interception. If they do provide a client certificate, forge all client\n      certificate metadata and use the forged client certificate in the\n      connection against the real server.\n\n    $ ratched --intercept www.johannes-bauer.com,c_certfile=joe.crt,c_keyfile=joe.key -o output.pcapng\n      Same as before, but for connections to johannes-bauer.com, do not forge\n      client certificates, but always use the given client certificate and key\n      (joe.crt / joe.key) for authentication against the server.\n\n    $ ratched --keyspec ecc:secp256r1 --ocsp-uri http://www.ocsp-server.com -o output.pcapng\n      Choose secp256r1 instead of RSA-2048 for all used certificates and\n      encode an OCSP Responder URI into those forged certificates as well.\n\n    $ ratched --initial-read-timeout 5.0 --default intercept=mandatory -o output.pcapng\n      Wait five seconds for connecting clients to send a valid ClientHello\n      message. If after five seconds nothing is received or if unknown (non-\n      TLS) traffic is received, terminate the connection instead of performing\n      unmodified forwarding.\n```\n\n[//]: # (End of help page -- auto-generated, do not edit!)\n\n# Naming\nThe name \"ratched\" alludes to nurse Ratched of \"One Flew Over The Cuckoo's\nNest\". If you use the tool to spy on people, you're a complete douchebag and\nabusing your power. You should watch the movie. Please use ratched responsibly\nto *increase* security of our infrastructure, not undermine it. TLS\ninterception for spying purposes is despicable and dangerous.\n\n# Dependencies\nratched requires at least OpenSSL v1.1.\n\n# License\nratched is licensed under the GNU GPL-3.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohndoe31415%2Fratched","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohndoe31415%2Fratched","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohndoe31415%2Fratched/lists"}