{"id":13522076,"url":"https://github.com/mikeperry-tor/vanguards","last_synced_at":"2025-04-04T23:07:27.334Z","repository":{"id":45710415,"uuid":"99290494","full_name":"mikeperry-tor/vanguards","owner":"mikeperry-tor","description":"Vanguards help guard you from getting vanned...","archived":false,"fork":false,"pushed_at":"2024-07-06T01:04:46.000Z","size":2536,"stargazers_count":227,"open_issues_count":28,"forks_count":25,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-28T22:14:39.240Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikeperry-tor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.rst","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":"2017-08-04T01:38:09.000Z","updated_at":"2025-03-12T07:01:26.000Z","dependencies_parsed_at":"2024-01-03T04:13:26.764Z","dependency_job_id":"23e6a238-1011-403b-b317-7c9a4273187f","html_url":"https://github.com/mikeperry-tor/vanguards","commit_stats":{"total_commits":407,"total_committers":6,"mean_commits":67.83333333333333,"dds":0.02211302211302213,"last_synced_commit":"10942de93f6578f8303f60014f34de2fca345545"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeperry-tor%2Fvanguards","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeperry-tor%2Fvanguards/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeperry-tor%2Fvanguards/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeperry-tor%2Fvanguards/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikeperry-tor","download_url":"https://codeload.github.com/mikeperry-tor/vanguards/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261603,"owners_count":20910108,"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-08-01T06:00:41.928Z","updated_at":"2025-04-04T23:07:27.303Z","avatar_url":"https://github.com/mikeperry-tor.png","language":"Python","funding_links":[],"categories":["Python","Uncategorized","Tor Onion服务防护","Tor Onion service defenses","Applications"],"sub_categories":["Uncategorized","威胁狩猎","Threat signature packages and collections","Other applications"],"readme":"# The Vanguards Onion Service Addon\n\n[![Build Status](https://travis-ci.org/mikeperry-tor/vanguards.png?branch=master)](https://travis-ci.org/mikeperry-tor/vanguards) [![Coverage Status](https://coveralls.io/repos/github/mikeperry-tor/vanguards/badge.png?branch=master)](https://coveralls.io/github/mikeperry-tor/vanguards?branch=master)\n\nEven after deployment of the [new v3 onion service\nprotocol](https://gitweb.torproject.org/torspec.git/tree/proposals/224-rend-spec-ng.txt),\nthe attacks facing onion services are wide-ranging, and still require\nmore extensive modifications to fix in Tor-core itself.\n\nBecause of this, we have decided to rapid-prototype these defenses in a\ncontroller addon in order to make them available ahead of their official\nTor-core release, for onion services that require high security as soon as\npossible.\n\nFor details about the defenses themselves, please see\n[README\\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_TECHNICAL.md).\n\nFor additional security information, please see\n[README\\_SECURITY.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md).\n\n# Installation Methods\n\nThere are several ways to use this addon.\n\nPackages for debian-like systems exist, but they are typically out of date.\nCheck backports, if you're lucky it might get updated there.\n\nIf you are using this addon with a system tor, and not using a system\nvanguards package, you will need to run the following as the system Tor user,\nbecause this addon needs access to Tor's data directory. To do this on\ndebian-like systems, do:\n\n```\n  sudo -u debian-tor bash\n```\n\nThen, run all of the following as the `debian-tor` user.\n\n## Running this addon directly from git\n\n**This is the safest option to use, since it avoids having pip and/or\nvirtualenv download packages from PYPI without verification.**\n\n1. Retrieve this repository and optionally verify a signed git version tag.\n2. [Install Stem](https://stem.torproject.org/download.html)\n3. Run **./src/vanguards.py**\n\nBy default, vanguards will try to connect to \"/run/tor/control\", and if that\nfails, will try control port 9051 (System Tor), and then 9151 (Tor Browser).\n\nIf your control port is on an alternate IP and Port, specify that with\n**--control_host _IP_ --control_port _portnum_**.\n\nIf you are using a different control socket path, specify its full path with\n**--control_socket /path/to/socket**.\n\nNote that **./src/vanguards.py** has several other options under **--help**.\n\n## Using VirtualEnv\n\n**This option tells virtualenv not to download packages, and only downloads\npip packages with --require-hashes. It should be safe.**\n\nTo install Stem and Vanguards into their own python virtualenv, run:\n\n```\ntorsocks ./setup.sh\nsource vanguardenv/bin/activate\nvanguards\n```\n\nIf you do not want your environment to be in the vanguardenv subdirectory, you\ncan specify a different directory as an argument to **setup.sh**.\n\n## Pip\n\nThis project is also listed on the Python Package Index. To install the\nlatest release via pip **without any verification**, do:\n\n```\ntorsocks pip install vanguards\n```\n\nIf your distribution provides pypy3 (see\n[Performance Tuning](#performance-tuning)), you can do:\n\n```\ntorsocks pypy3 -m pip install vanguards\n```\n\n# How to use the addon\n\n## Configuration\n\nAll of the subsystems of this addon can be tuned via a configuration file.\nCheck out this documented [example configuration file](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards-example.conf) for more information.\n\nConfiguration files can be specified on the command line. The default is to\nread **vanguards.conf** from the current working directory. If the environment\nvariable **$VANGUARDS\\_CONFIG** is set, the config file will be read from the\nfile specified in that variable.\n\n## Onion service use\n\nThis addon is primarily intended for onion service operators. To use it,\nset up your onion service to expose a control port listener using the\nControlPort or ControlSocket torrc directives:\n\n```\nControlPort 9099             # or ControlSocket /path/to/socket\nCookieAuthentication 1\nDataDirectory /path/to/tor/datadir\n```\n\nand then run:\n\n```\nvanguards --control_port 9099     # (or --control_socket /path/to/socket).\n```\n\n## Client use\n\nIt is also possible to use the vanguards addon as a regular Tor client with\nTor Browser or with Onionshare.\n\nTo use it with Tor Browser, all you have to do is start Tor Browser, and then run:\n```\n  ./src/vanguards.py\n```\n\nIf you also have a system Tor, you will need to specify Tor Browser's control\nport with `--control_port 9151`\n\nTo use it with Onionshare, set up your Tor to expose a control port and attach\nboth onionshare and the vanguards addon to it.\n\n## Performance Tuning\n\nFor very high traffic onion services, we recommend using\n[PyPy](https://pypy.org) instead of CPython. PyPy contains a JIT that should\nmake this addon run considerably faster.\n\nThe easiest way to use PyPy is to do **sudo apt-get install pypy3** or\nequivalent before running **./setup.sh** as per above. The setup.sh script will\nthen see that pypy is installed, and use it by default in the resulting\nvirtualenv.\n\nTo switch to pypy after running **setup.sh**, simply remove the vanguardenv\ndirectory and run **setup.sh** again.\n\nIf you want to use pypy outside of a virtualenv, install Stem 1.7.0 or later\non your system, and then run the addon directly from the source tree with:\n\n```\n  pypy3 ./src/vanguards.py\n```\n\nAdditionally, you can try running vanguards components in parallel, so that\nthe system does not bottleneck on one CPU core. A simple test script called\n[vanguards\\_parallel.sh](https://github.com/mikeperry-tor/vanguards/blob/master/vanguards_parallel.sh)\nis available to try this. If it helps,\n[please let us know](https://github.com/mikeperry-tor/vanguards/issues/62)!\n\nVanguards by itself should not require much overhead, but if even that is too\nmuch, you can run the following once per hour from cron to update your torrc\nwith fresh layer2 and layer3 guards:\n\n```\n  ./src/vanguards.py --one_shot_vanguards\n```\n\n# What do the logs mean?\n\nThis is an experimental addon with many heuristics that still need tuning.\nEvents that represent severe issues are at WARN level. You should\n[react to these events](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md#monitor-your-service).\n\nWarns are currently emitted for the following conditions:\n\n1. When your service is disconnected from the Tor network, we WARN. Downtime\ncan be a side channel signal or a passive information leak,\nand you should ensure your Internet connection is reliable to minimize\ndowntime of your service as much as possible.\n2. When a hidden service descriptor circuit sends more than 30KB, we WARN. If this\nhappens, it is either a bug, a heavily-modified hidden service descriptor,\nor an actual attack.\n3. When you set ExcludeNodes in Tor to exclude countries, but do not give\nTor a GeoIP file, we WARN.\n4. If you disable killing circuits in the rendguard component, we WARN when\nuse counts for rends are exceeded.\n5. We WARN upon receipt of any cell that the Tor client drops or ignores.\n6. If you enable introduction circuit rate limiting, a WARN is emitted when\nintroduction circuits are killed.\n\nEvents that are detected by heuristics that still need tuning are at NOTICE\nlevel. They may be a bug, a false positive, or an actual attack. If in doubt,\ndon't panic. Please check the [Github\nissues](https://github.com/mikeperry-tor/vanguards/issues/) to see if any\nknown false positives are related to these lines, and if not, consider filing\nan issue. Please redact any relay fingerprints from the messages before\nposting.\n\n# What else should I read?\n\nFor technical details about the defenses that this addon provides, please see\n[README\\_TECHNICAL.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_TECHNICAL.md).\n\nFor additional security information, please see\n[README\\_SECURITY.md](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeperry-tor%2Fvanguards","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeperry-tor%2Fvanguards","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeperry-tor%2Fvanguards/lists"}