{"id":20010192,"url":"https://github.com/activecm/smudge","last_synced_at":"2025-05-04T20:30:44.694Z","repository":{"id":45055651,"uuid":"513301563","full_name":"activecm/smudge","owner":"activecm","description":"Passive OS detection based on SYN packets without Transmitting any Data","archived":false,"fork":false,"pushed_at":"2023-03-29T11:23:46.000Z","size":525,"stargazers_count":46,"open_issues_count":5,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-30T22:41:59.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/activecm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2022-07-12T21:49:14.000Z","updated_at":"2025-03-17T00:55:56.000Z","dependencies_parsed_at":"2023-02-08T16:31:38.906Z","dependency_job_id":null,"html_url":"https://github.com/activecm/smudge","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fsmudge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fsmudge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fsmudge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fsmudge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/activecm","download_url":"https://codeload.github.com/activecm/smudge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252395175,"owners_count":21740977,"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":[],"created_at":"2024-11-13T07:18:48.168Z","updated_at":"2025-05-04T20:30:44.082Z","avatar_url":"https://github.com/activecm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv id=\"top\"\u003e\u003c/div\u003e\n\n\n\u003c!-- PROJECT SHIELDS --\u003e\n[![PyPI version][pypi-shield]][pypi-url]\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n\n\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/activecm/smudge\"\u003e\n    \u003cimg src=\"images/smudge.png\" alt=\"Logo\" width=\"600\" height=\"600\"\u003e\n  \u003c/a\u003e\n\n\u003ch3 align=\"center\"\u003eSmudge\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    project_description\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/activecm/smudge\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/activecm/smudge\"\u003eView Demo\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/activecm/smudge/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/activecm/smudge/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#signatures\"\u003eSignatures\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#Code of Conduct\"\u003eCode of Conduct\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#logo\"\u003eLogo\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\n\u003ca href=\"https://github.com/activecm/smudge\"\u003e\n    \u003cimg src=\"images/smudge_screenshot.png\" alt=\"Screenshot\" width=\"900\" height=\"500\"\u003e\n\u003c/a\u003e\n\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n### Built With\n\n* [Python](https://www.python.org/)\n* [Scapy](https://scapy.net/)\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n### Prerequisites\n\nEnsure that scapy is installed:\n[Scapy Install](https://scapy.readthedocs.io/en/latest/installation.html#installing-scapy-v2-x/)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nSmudge is a component of Active Countermeasure's Passer. It can be called from the command line via the following arguments:\n\n\u003ca\u003e `-c, --colored-text`\u003cbr/\u003eDisable colored text output.\u003c/a\u003e\u003cbr/\u003e\n\u003ca\u003e `-d, --database`\u003cbr/\u003eDisable local SQlite db creation. \u003c/a\u003e\u003cbr/\u003e\n\u003ca\u003e `-i, --interface`\u003cbr/\u003eSpecifies network interface that traffic will be sniffed on. \u003c/a\u003e\u003cbr/\u003e\n\u003ca\u003e `-l, --list`\u003cbr/\u003eList available network interface that traffic can be sniffed on. \u003c/a\u003e\u003cbr/\u003e\n\u003ca\u003e `-r, --read`\u003cbr/\u003eSpecifies PCAP file that will be read by SMUDGE. \u003c/a\u003e\u003cbr/\u003e\n\n_For more examples, please refer to the [Documentation](https://example.com)_\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- Signatures --\u003e\n## Create Your Own Signatures\n\nCurrently **SMUDGE** only detects signatures from TCP SYN packets. TCP SYN packets are passively sniffed with **Passer**. If **SMUDGE** is enabled, the a signature is generated and it is searched for in the database. Signatures need to be created from known sources to add additional entries into our database.\n\nA signature for a TCP SYN packet look like this:\n\n```\nsig = ver:ittl:olen:mss:wsize,scale:olayout:quirks:pclass\n```\n\n---\n\n### Version\n`ver` - signature for IPv4 ('4'), IPv6 ('6'), or both ('*').\n\n---\n\n### Initial Time to Live\n`ittl` - initial TTL used by the OS. Almost all operating systems use 64, 128, or 255; ancient versions of Windows sometimes used 32, and several obscure systems sometimes resort to odd values such as 60.\n\n---\n\n### Options Length\n`olen` - length of IPv4 options or IPv6 extension headers. Usually zero for normal IPv4 traffic; always zero for IPv6 due to the limitations of libpcap/winpcap/npcap. \n\n---\n\n### Maximum Segment Size\n`mss`  - maximum segment size, if specified in TCP options. Special value of '*' can be used to denote that MSS varies depending on the parameters of sender's network link, and should not be a part of the signature. In this case, MSS will be used to guess the type of network hookup according to the [mtu] rules.\n\n--- \n\n### Window Size\n`wsize` - window size. Can be expressed as a fixed value, but many operating systems set it to a multiple of MSS or MTU, or a multiple of some random integer. **SMUDGE** allows notation such as 'mss*4', 'mtu*4', or '%8192' to be used. Wilcard ('*') is possible too.\n\n---\n\n### Window Scaling Factor\n`scale` - window scaling factor, if specified in TCP options. Fixed value or '*'.\n\n---\n\n### Options Layout\n`olayout` - comma-delimited layout and ordering of TCP option. This is a longer string and is comprised of several values.\n \n| Item        | Description                                             | \n| ----------- | -----------                                             |\n| eol+n       | explicit end of options, followed by n bytes of padding | \n| nop         | no-op option                                            |\n| mss         | maximum segment size                                    |\n| ws          | window scaling                                          |\n| sok         | selective ACK permitted                                 |\n| sack        | selective ACK (should not be seen)                      |\n| ts          | timestamp                                               |\n| ?n          | unknown option ID n                                     |\n\n---\n\n### Quirks\n`quirks`     - comma-delimited properties and quirks observed in IP or TCP headers.\n\nThe definition of a quirk is a `peculiar behavioral habit`. When quirks are observed in IP/TCP headers, it is import to ensure that they continue to be observed. Quirks may not present themselves the same way everytime. Do your best to find items on this list that offer repeatability.\n\n| Item        | Description                                             | \n| ----------- | -----------                                             |\n| df          | \"don't fragment\" set (probably PMTUD); ignored for IPv6 | \n| id+         | DF set but IPID non-zero; ignored for IPv6              |\n| id-         | DF not set but IPID is zero; ignored for IPv6           |\n| ecn         | explicit congestion notification support                |\n| 0+          | \"must be zero\" field not zero; ignored for IPv6         |\n| flow        | non-zero IPv6 flow ID; ignored for IPv4                 |\n|             |                                                         |\n| seq-        | sequence number is zero                                 |\n| ack+        | ACK number is non-zero, but ACK flag not set            |\n| ack-        | ACK number is zero, but ACK flag set                    |\n| uptr+       | URG pointer is non-zero, but URG flag not set           |\n| urgf+       | URG flag used                                           |\n| pushf+      | PUSH flag used                                          |\n|             |                                                         |\n| ts1-        | own timestamp specified as zero                         |\n| ts2+        | non-zero peer timestamp on initial SYN                  |\n| opt+        | trailing non-zero data in options segment               |\n| exws        | excessive window scaling factor (\u003e 14)                  |\n| bad         | malformed TCP options                                   |\n\n---\n\n### Payload Size Classification\n`pclass`     - payload size classification: '0' for zero, '+' for non-zero, '*' for any. The packets we fingerprint right now normally have no payloads, but some corner cases exist.\n\n---\n\nThis repository includes a tool called \"sig_gen.py\". This tool can be leveraged to create signatures from known sources. Signatures are created in the same format as p0f and information about the signature format can be found here [p0f](https://github.com/p0f/p0f).\n\nSignatures are stored in a Github Repository maintained by Active Countermeasures that can be found here [tcp-sig-json](https://github.com/activecm/tcp-sig-json).\nAdding a new signature is as easy creating a new pull request.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\n\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\nThis project uses pylint. Github actions are set up to run the a linter on the code at merge. Please manually run the linter to catch any issues before pull request is created.\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the MIT License. See `LICENSE.txt` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- Code of Conduct --\u003e\n## Code of Conduct\n\nThe SMUDGE project has adopted Contributor Covenant's code of conduct. See `CODE_OF_CONDUCT.md` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nDavid Quartarolo - [@d_quartarolo](https://twitter.com/d_quartarolo) - david@activecountermeasures.com\n\nProject Link: [https://github.com/activecm/smudge](https://github.com/activecm/smudge)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- ACKNOWLEDGMENTS --\u003e\n## Acknowledgments\n\n* [Bill Stearns](https://github.com/william-stearns)\n  Bill has been working with me on this from day 1. Checkout Bill's Site [here](http://www.stearns.org/)\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n[pypi-shield]: https://badge.fury.io/py/smudge.svg\n[pypi-url]: https://badge.fury.io/py/smudge\n[contributors-shield]: https://img.shields.io/github/contributors/activecm/smudge\n[contributors-url]: https://github.com/activecm/smudge/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/activecm/smudge\n[forks-url]: https://github.com/activecm/smudge/network/members\n[stars-shield]: https://img.shields.io/github/stars/activecm/smudge\n[stars-url]: https://github.com/activecm/smudge/stargazers\n[issues-shield]: https://img.shields.io/github/issues/activecm/smudge\n[issues-url]: https://github.com/activecm/smudge/issues\n[license-shield]: https://img.shields.io/github/license/activecm/smudge\n[license-url]: https://github.com/activecm/smudge/blob/master/LICENSE.txt\n[product-screenshot]: images/screenshot.png\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factivecm%2Fsmudge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Factivecm%2Fsmudge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factivecm%2Fsmudge/lists"}