{"id":20317923,"url":"https://github.com/crowdsecurity/pycrowdsec","last_synced_at":"2025-10-11T12:33:47.568Z","repository":{"id":37480475,"uuid":"392213714","full_name":"crowdsecurity/pycrowdsec","owner":"crowdsecurity","description":null,"archived":false,"fork":false,"pushed_at":"2023-09-05T07:48:17.000Z","size":122,"stargazers_count":12,"open_issues_count":0,"forks_count":3,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-05T20:33:37.589Z","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/crowdsecurity.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":"2021-08-03T06:25:13.000Z","updated_at":"2024-12-28T16:06:01.000Z","dependencies_parsed_at":"2024-11-14T18:51:26.583Z","dependency_job_id":null,"html_url":"https://github.com/crowdsecurity/pycrowdsec","commit_stats":{"total_commits":30,"total_committers":3,"mean_commits":10.0,"dds":"0.43333333333333335","last_synced_commit":"941dca3280886989c8c65cca56a89c5447bdf407"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdsecurity%2Fpycrowdsec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdsecurity%2Fpycrowdsec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdsecurity%2Fpycrowdsec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdsecurity%2Fpycrowdsec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crowdsecurity","download_url":"https://codeload.github.com/crowdsecurity/pycrowdsec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248456376,"owners_count":21106602,"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-14T18:37:18.801Z","updated_at":"2025-10-11T12:33:42.535Z","avatar_url":"https://github.com/crowdsecurity.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=center\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/crowdsecurity/pycrowdsec/main/assets/pycrowdsec.jpg\" width=\"280\" height=\"300\" \u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://gitter.im/crowdsec-project/community\"\u003e\u003cimg src=\"https://badges.gitter.im/gitterHQ/gitter.png\"\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\"\u003e\n\u003c/p\u003e\n\n# PyCrowdSec\n\n[CrowdSec](https://github.com/crowdsecurity/crowdsec) is a FOSS tool which parses logs and detects attacks. PyCrowdSec enables integration of CrowdSec with python projects. It is easy to setup and boosts the security by leveraging CrowdSec's attack detection capabilities.\n\nPyCrowdSec contains a python client library for CrowdSec, as well as middlewares for django and flask integrations.\n\n## Installation:\n\n```bash\npip install pycrowdsec\n```\n\nYou'll also need an instance of CrowdSec running, see installation instructions [here](https://docs.crowdsec.net/Crowdsec/v1/getting_started/installation/)\n\n## Client library:\n\n### StreamClient\n\nThis client polls CrowdSec LAPI and keeps track of active decisions.\nIn the below example assume that there's a ban decisions for IP \"77.88.99.66\" and captcha decision for country \"CN\".\n\n**Basic Usage:**\n\n```python\nfrom pycrowdsec.client import StreamClient\nclient = StreamClient(\n    api_key=\u003cCROWDSEC_API_KEY\u003e,\n)\n\nclient.run() # This starts polling the API\n\nassert client.get_current_decisions() == {\n    \"77.88.99.66\": \"ban\"\n    \"CN\": \"captcha\"\n}\n\nassert client.get_action_for(\"77.88.99.66\") == \"ban\"\nassert client.get_action_for(\"CN\") == \"captcha\"\n```\n\nThe `CROWDSEC_API_KEY` can be obtained by running \n```bash\nsudo cscli bouncers add python_bouncer\n```\n\nThe `StreamClient`'s constructor also accepts the following optional parameters for more advanced configurations.\n\n**lapi_url** : str\n    Base URL of CrowdSec API. Default is http://localhost:8080/ .\n\n**interval** : int\n    Query the CrowdSec API every \"interval\" second\n\n**user_agent** : str\n    User agent to use while calling the API.\n\n**scopes** : List[str]\n    List of decision scopes which shall be fetched. Default is [\"ip\", \"range\"]\n\n### QueryClient\n\nThis client will query CrowdSec LAPI to check whether the requested item has any decisions against it.\nIn the below example assume that there's a ban decisions for IP \"77.88.99.66\" and captcha decision for country \"CN\".\n\n\n**Basic Usage:**\n\n```python\n\nfrom pycrowdsec.client import StreamClient\nclient = StreamClient(\n    api_key=\u003cCROWDSEC_API_KEY\u003e,\n)\n\nclient.run() # This starts polling the API\n\nassert client.get_action_for(\"77.88.99.66\") == \"ban\"\nassert client.get_action_for(\"CN\") == \"captcha\"\n\n```\n\nThe `QueryClient`'s constructor also accepts the following optional parameters for more advanced configurations.\n\n**lapi_url** : str\n    Base URL of CrowdSec API. Default is http://localhost:8080/ .\n\n**user_agent** : str\n    User agent to use while calling the API.\n\n\n## Flask Integration:\n\nSee `./examples/flask` for more detailed example (includes captcha remediation too).\n\nA minimal flask app with PyCrowdSec protection would look like:\n```python\nfrom flask import Flask\n\nfrom pycrowdsec.client import StreamClient\nfrom pycrowdsec.flask import get_crowdsec_middleware\n\nclient = StreamClient(api_key=\u003cCROWDSEC_API_KEY\u003e)\napp = Flask(__name__)\napp.before_request(\n    get_crowdsec_middleware(actions, c.cache, exclude_views=[\"ban_page\"]\n)\n\nactions = {\n    \"ban\": lambda: redirect(url_for(\"ban_page\")),\n}\n\n@app.route(\"/ban\")\ndef ban_page():\n    return abort(403)\n\n@app.route(\"/\")\ndef index():\n    return \"Hello\"\n\nif __name__ = \"__main__\":\n    app.run(host=\"0.0.0.0\")\n```\n\n## Django Integration:\n\nSee `./examples/django` for more detailed example (includes captcha remediation too).\n\nAfter installing `pycrowdsec`, in your `settings.py` add the following line in the `MIDDLEWARE` list\n\n```python\nMIDDLEWARE = [\n    .........\n    \"pycrowdsec.django.crowdsec_middleware\",\n    .........\n]\n```\n\nNext add define the following variables required for `pycrowdsec` to function.\n\n```python\nPYCROWDSEC_LAPI_KEY = \u003cYOUR_LAPI_KEY\u003e\nPYCROWDSEC_ACTIONS = {\n    \"ban\": lambda request: redirect(reverse(\"ban_view\")),\n}\n# IMPORTANT: If any action is doing a redirect to some view, always exclude it for pycrowdsec. Otherwise the middleware will trigger the redirect on the action view too.\nPYCROWDSEC_EXCLUDE_VIEWS = {\"ban_view\"}\n```\n\n\nYou'll also need to register a view with name `ban_view`. In this example all the banned IPs would be redirected to the `ban_view`\n\nFor more advanced configurations, you can specify the following variables in your `settings.py`\n\n**PYCROWDSEC_POLL_INTERVAL**  int : Query the CrowdSec API every `PYCROWDSEC_POLL_INTERVAL` seconds.\n\n**PYCROWDSEC_LAPI_URL** str: Base URL of CrowdSec API.\n\n**PYCROWDSEC_ACTIONS** Dict[str, Callable]: Action to be taken when some request matches CrowdSec's decision.\n\n**PYCROWDSEC_REQUEST_TRANSFORMERS** List[Callable]: Obtains value from Django Request object, this value is used to match the request with CrowdSec's decisions. By default it contains only one transformer which obtains IP from the request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdsecurity%2Fpycrowdsec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowdsecurity%2Fpycrowdsec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdsecurity%2Fpycrowdsec/lists"}