<p align="center"><a rel="noreferrer noopener" href="https://github.com/tn3w/flask_Captchaify"><img alt="Github" src="https://img.shields.io/badge/Github-141e24.svg?&style=for-the-badge&logo=github&logoColor=white"></a> <a rel="noreferrer noopener" href="https://pypi.org/project/flask-Captchaify/"><img alt="PyPI" src="https://img.shields.io/badge/PyPi-141e24.svg?&style=for-the-badge&logo=python&logoColor=white"></a> <a rel="noreferrer noopener" href="https://libraries.io/pypi/flask-Captchaify"><img alt="Libraries.io" src="https://img.shields.io/badge/Libraries.io-141e24.svg?&style=for-the-badge&logo=npm&logoColor=white"></a>
A DDoS defense system for flask applications, first sends users to a captcha page without a javascript script and creates a confirmation cookie/url arg after the captcha.
Todos:
- [ ] Captcha type with images of emojis
- [ ] Captcha type with pictures of animals
- [ ] Captcha or blocking rules based on client_ip and client_ip_info (e.g. blocking of certain IP countries)
## How does flask_Captchaify work?
If needed, a captcha is displayed to the user (or the robot) based on the strength set. Javascript is not needed for this, as the content is rendered on the server.
An example script could look like this:
```python
from flask import Flask
from flask_Captchaify import Captcha
app = Flask(__name__)
captcha = Captcha(app, default_hardness=2, default_action = "fight")
@app.route("/")
def index():
return 'Hello Human!'
if __name__ == "__main__":
app.run(host = "localhost", port = 8080)
```
> [!TIP]
> 🎉 flask_Captchaify will soon have a new type of captcha [Preview](https://github.com/tn3w/flask_Captchaify/releases/tag/prev_v1.7)
## Application purposes
A few application purposes:
- Protect against DDoS attacks
- Your website contains content that should not be read by a robot
- A login website
- A dark web page that simply needs to be secured a bit
### Why should you use Captchaify if you host a Flask server?
A quick and easy implementation allows even small websites or a small team of developers to quickly get robot protection. It also doesn't use third-party providers, which limits data collection from Google, Facebook and the creepy data brokers. Everything is open source, meaning you can rewrite the code yourself and perhaps make it more private.
# Instructions
## Installation guide
1. Make sure you have the latest version of Python and Pip installed, you also need git installed.
2. Install the script with pip `pip install flask_Captchaify` or manually via `git clone https://github.com/tn3w/flask_Captchaify` or download the zip.
3. If you installed it manually, make sure your python script is in the folder where there is a subfolder flask_Captchaify, and make sure you run `pip install -r requirements.txt` in the flask_Captchaify folder.
5. Make sure that after:
```python
app = Flask(__name__)
```
You add the line:
```python
captcha = Captcha(app, default_hardness=2, default_action = "fight")
```
And at the beginning of the file add the import:
```python
from flask_Captchaify import Captcha
```
For more information, see the sample code above.
## Personalization
1. `actions` Arg
To change the response in the case of certain routes / endpoints, you can use the actions parameter.
Example of a website that allows all bots on the main page, enforces captchas on the login page, and blocks all robots on the registration page:
```python
captcha = Captcha(app, actions={"/": "let", "/login": "fight", "/register": "block"})
```
When using "*" before or after the urlpath / endpoint you can address multiple urls.
Example of a website where all urls with /api/ are allowed through, all urls starting with "/dogs/" show everyone a captcha and all urls ending with "/cats/" block bots:
```python
captcha = Captcha(app, actions={"*/api/*": "let", "/dogs/*": "fight", "*/cats/": "block"})
```
All actions:
| Name of action | Executing Action |
| -------------- | -------------------------------------------------------------------- |
| let | Allows all traffic through, regardless of whether the IP is blocked. |
| block | Blocks all traffic if it is blocked, without captcha. |
| fight | Displays a captcha to all traffic, whether suspicious or not. |
| captcha | Default value, shows only suspicious traffic captchas. |
<br>
2. `hardness` Arg
To change the hardness of a captcha for specific routes or endpoints use hardness.
Example of a website that sets the hardness of the main page to 1 (= easy), on the login page to 2 (= normal) and on the register page to 3 (= hard):
```python
captcha = Captcha(app, hardness={"/": 1, "/login": 2, "/register": 3})
```
When using "*" before or after the urlpath / endpoint you can address multiple urls, like actions.
All hardness levels:
| Hardness Level | Captcha modification |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 1 | The captcha is easy. Only a text captcha with 6 - 8 characters is displayed |
| 2 | The captcha is normal. Only a text captcha with 9 - 11 characters is displayed |
| 3 | The hardness of the captcha is hard, a 9 - 14 number audio captcha is displayed in addition to the 10 - 12 character text captcha. |
<br>
3. `rate_limits` Arg
To change the rate_limit and max_rate_limit for a specific route or endpoint use the rate_limits arg.
The syntax is a bit different from the others, because two values are specified `{"route": (rate_limit, max_rate_limit), "endpoint": (rate_limit, max_rate_limit)}`. The variable rate_limit must be a number indicating how many requests per minute can come from a given ip. max_rate_limit indicates how many requests can come from all ips per minute, also a number.
Example of a website that has a specific rate_limit on /api/:
```python
captcha = Captcha(app, template_dirs={"/api/*": (60, 600)})
```
<br>
4. `template_dirs` Arg
To change the template directory of a particular route use the template_dirs arg.
Example of a website that has a specific template directory on /api/:
```python
captcha = Captcha(app, template_dirs={"/api/*": "/path/to/special/template/directory"})
```
A template directory can look like this:
```
template_directory\
\captcha.html
\block.html
\rate_limited.html
\change_language.html
```
If one of the three templates does not exist in the folder, a 404 error is displayed when calling it. e.g. if you remove the changelanguage page at apis.
<br>
5. `default_action` Arg
To specify the default action of all routes or endpoints use the default_action arg.
Example of a very paranoid website that has set its action to "fight" for all routes:
```python
captcha = Captcha(app, default_action="fight")
```
<br>
6. `default_hardness` Arg
To specify the default hardness of all routes or endpoints use the default_hardness arg.
Example of a very paranoid website that has set its hardness to 3 (= hard) for all routes:
```python
captcha = Captcha(app, default_hardness=3)
```
<br>
7. `default_rate_limit` Arg
To specify the default requests of an IP per minute for all routes use the default_rate_limit variable. (Default: 120 = 2 requests per second per IP)
Example of a web page with custom rate_limit:
```python
captcha = Captcha(app, default_rate_limit=60)
```
<br>
8. `default_max_rate_limit` Arg
To specify the default requests of all IPs per minute for all routes use the default_max_rate_limit variable. (Default: 1200 = 2 requests per second from 10 IPs)
Example of a web page with custom max_rate_limit:
```python
captcha = Captcha(app, default_max_rate_limit=600)
```
<br>
9. `default_template_dir` Arg
To specify the default template_dir of all routes or endpoints use the default_template_dir arg.
Example of a web page with custom template_dir:
```python
captcha = Captcha(app, default_template_dir="/path/to/my/custom/template/directory")
```
<br>
9. `verification_age` Arg
Indicates the time in seconds how long a solved captcha is valid (Default: 3600 = 1 hour)
Website with 3 hours verification_age:
```python
captcha = Captcha(app, verification_age=10800)
```
<br>
9. `without_cookies` Arg
If True, no cookies are created, and verification is proven via URL args (Default: False)
Website with without_cookies enabled:
```python
captcha = Captcha(app, without_cookies=True)
```
<br>
9. `block_crawler` Arg
If True, crawlers like Googlebot, further are estimated via their user agent as suspicious and not the website, good for websites that should not be crawled (Default: True)
Web page with block_crawler enabled:
```python
captcha = Captcha(app, block_crawler=True)
```
<br>
9. `crawler_hints` Arg:
If True, crawlers like Googlebot, are shown meta tags and the title of a normal web page, while they would have to solve a captcha. (Default: True)
Web page with crawler_hints disabled:
```python
captcha = Captcha(app, crawler_hints=False)
```
<br>
9. `third_parties` Arg:
Specifies which third parties are used to check the IP addresses. By default, all 3 third parties are used. (See list)
Web page that only asks a third party for Tor Ip addresses:
```python
captcha = Captcha(app, third_parties=["tor"])
```
Possible entries would be:
| Abbreviation | Who is requested and how does the evaluation mechanism work? |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| tor | [SecOps-Institute/Tor-IP-Addresses](https://raw.githubusercontent.com/SecOps-Institute/Tor-IP-Addresses/master/tor-exit-nodes.lst) on GitHub is asked for Tor Ipv4 and Ipv6 addresses and the Ip address is compared with this list |
| ipapi | [Ipapi](https://ipapi.com) is requested with the Ip and the result of the fields "proxy" and "hosting" is used |
| stopforumspam | [StopForumSpam](https://stopforumspam.com) is requested and the result is used |
<br>
Raw data
{
"_id": null,
"home_page": "https://github.com/tn3w/flask_Captchaify",
"name": "flask-Captchaify",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "flask,Python,Bot,Captcha,DDoS",
"author": "TN3W",
"author_email": "tn3wA8xxfuVMs2@proton.me",
"download_url": "https://files.pythonhosted.org/packages/71/e4/95d996040b5d9f4945507079d06b3491598705c84da41740e4cbf05f00c1/flask_Captchaify-1.6.7.2.tar.gz",
"platform": null,
"description": "<p align=\"center\"><a rel=\"noreferrer noopener\" href=\"https://github.com/tn3w/flask_Captchaify\"><img alt=\"Github\" src=\"https://img.shields.io/badge/Github-141e24.svg?&style=for-the-badge&logo=github&logoColor=white\"></a> <a rel=\"noreferrer noopener\" href=\"https://pypi.org/project/flask-Captchaify/\"><img alt=\"PyPI\" src=\"https://img.shields.io/badge/PyPi-141e24.svg?&style=for-the-badge&logo=python&logoColor=white\"></a> <a rel=\"noreferrer noopener\" href=\"https://libraries.io/pypi/flask-Captchaify\"><img alt=\"Libraries.io\" src=\"https://img.shields.io/badge/Libraries.io-141e24.svg?&style=for-the-badge&logo=npm&logoColor=white\"></a>\n\nA DDoS defense system for flask applications, first sends users to a captcha page without a javascript script and creates a confirmation cookie/url arg after the captcha.\n\nTodos:\n- [ ] Captcha type with images of emojis\n- [ ] Captcha type with pictures of animals\n- [ ] Captcha or blocking rules based on client_ip and client_ip_info (e.g. blocking of certain IP countries)\n\n## How does flask_Captchaify work?\nIf needed, a captcha is displayed to the user (or the robot) based on the strength set. Javascript is not needed for this, as the content is rendered on the server.\n\nAn example script could look like this:\n```python\nfrom flask import Flask\nfrom flask_Captchaify import Captcha\n\napp = Flask(__name__)\ncaptcha = Captcha(app, default_hardness=2, default_action = \"fight\")\n\n@app.route(\"/\")\ndef index():\n return 'Hello Human!'\n\nif __name__ == \"__main__\":\n app.run(host = \"localhost\", port = 8080)\n```\n\n> [!TIP]\n> \ud83c\udf89 flask_Captchaify will soon have a new type of captcha [Preview](https://github.com/tn3w/flask_Captchaify/releases/tag/prev_v1.7)\n\n## Application purposes\nA few application purposes:\n - Protect against DDoS attacks \n - Your website contains content that should not be read by a robot\n - A login website\n - A dark web page that simply needs to be secured a bit\n\n### Why should you use Captchaify if you host a Flask server?\nA quick and easy implementation allows even small websites or a small team of developers to quickly get robot protection. It also doesn't use third-party providers, which limits data collection from Google, Facebook and the creepy data brokers. Everything is open source, meaning you can rewrite the code yourself and perhaps make it more private.\n\n# Instructions\n\n## Installation guide\n1. Make sure you have the latest version of Python and Pip installed, you also need git installed.\n2. Install the script with pip `pip install flask_Captchaify` or manually via `git clone https://github.com/tn3w/flask_Captchaify` or download the zip.\n3. If you installed it manually, make sure your python script is in the folder where there is a subfolder flask_Captchaify, and make sure you run `pip install -r requirements.txt` in the flask_Captchaify folder.\n5. Make sure that after:\n ```python\n app = Flask(__name__)\n ```\n You add the line:\n ```python\n captcha = Captcha(app, default_hardness=2, default_action = \"fight\")\n ```\n And at the beginning of the file add the import:\n ```python\n from flask_Captchaify import Captcha\n ```\nFor more information, see the sample code above.\n## Personalization\n\n1. `actions` Arg\n\n To change the response in the case of certain routes / endpoints, you can use the actions parameter.\n \n Example of a website that allows all bots on the main page, enforces captchas on the login page, and blocks all robots on the registration page:\n ```python\n captcha = Captcha(app, actions={\"/\": \"let\", \"/login\": \"fight\", \"/register\": \"block\"})\n ```\n\n When using \"*\" before or after the urlpath / endpoint you can address multiple urls.\n\n Example of a website where all urls with /api/ are allowed through, all urls starting with \"/dogs/\" show everyone a captcha and all urls ending with \"/cats/\" block bots:\n ```python\n captcha = Captcha(app, actions={\"*/api/*\": \"let\", \"/dogs/*\": \"fight\", \"*/cats/\": \"block\"})\n ```\n \n All actions:\n | Name of action | Executing Action |\n | -------------- | -------------------------------------------------------------------- |\n | let | Allows all traffic through, regardless of whether the IP is blocked. |\n | block | Blocks all traffic if it is blocked, without captcha. |\n | fight | Displays a captcha to all traffic, whether suspicious or not. |\n | captcha | Default value, shows only suspicious traffic captchas. |\n <br>\n\n2. `hardness` Arg\n \n To change the hardness of a captcha for specific routes or endpoints use hardness.\n\n Example of a website that sets the hardness of the main page to 1 (= easy), on the login page to 2 (= normal) and on the register page to 3 (= hard):\n ```python\n captcha = Captcha(app, hardness={\"/\": 1, \"/login\": 2, \"/register\": 3})\n ```\n\n When using \"*\" before or after the urlpath / endpoint you can address multiple urls, like actions.\n\n All hardness levels:\n | Hardness Level | Captcha modification |\n | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n | 1 | The captcha is easy. Only a text captcha with 6 - 8 characters is displayed |\n | 2 | The captcha is normal. Only a text captcha with 9 - 11 characters is displayed |\n | 3 | The hardness of the captcha is hard, a 9 - 14 number audio captcha is displayed in addition to the 10 - 12 character text captcha. |\n <br>\n\n3. `rate_limits` Arg\n\n To change the rate_limit and max_rate_limit for a specific route or endpoint use the rate_limits arg.\n The syntax is a bit different from the others, because two values are specified `{\"route\": (rate_limit, max_rate_limit), \"endpoint\": (rate_limit, max_rate_limit)}`. The variable rate_limit must be a number indicating how many requests per minute can come from a given ip. max_rate_limit indicates how many requests can come from all ips per minute, also a number.\n\n Example of a website that has a specific rate_limit on /api/:\n ```python\n captcha = Captcha(app, template_dirs={\"/api/*\": (60, 600)})\n ```\n <br>\n\n4. `template_dirs` Arg\n\n To change the template directory of a particular route use the template_dirs arg.\n\n Example of a website that has a specific template directory on /api/:\n ```python\n captcha = Captcha(app, template_dirs={\"/api/*\": \"/path/to/special/template/directory\"})\n ```\n\n A template directory can look like this:\n ```\n template_directory\\\n \\captcha.html\n \\block.html\n \\rate_limited.html\n \\change_language.html\n ```\n\n If one of the three templates does not exist in the folder, a 404 error is displayed when calling it. e.g. if you remove the changelanguage page at apis.\n <br>\n\n5. `default_action` Arg\n\n To specify the default action of all routes or endpoints use the default_action arg.\n\n Example of a very paranoid website that has set its action to \"fight\" for all routes:\n ```python\n captcha = Captcha(app, default_action=\"fight\")\n ```\n <br>\n\n6. `default_hardness` Arg\n\n To specify the default hardness of all routes or endpoints use the default_hardness arg.\n\n Example of a very paranoid website that has set its hardness to 3 (= hard) for all routes:\n ```python\n captcha = Captcha(app, default_hardness=3)\n ```\n <br>\n\n7. `default_rate_limit` Arg\n\n To specify the default requests of an IP per minute for all routes use the default_rate_limit variable. (Default: 120 = 2 requests per second per IP)\n\n Example of a web page with custom rate_limit:\n ```python\n captcha = Captcha(app, default_rate_limit=60)\n ```\n <br>\n\n8. `default_max_rate_limit` Arg\n\n To specify the default requests of all IPs per minute for all routes use the default_max_rate_limit variable. (Default: 1200 = 2 requests per second from 10 IPs)\n\n Example of a web page with custom max_rate_limit:\n ```python\n captcha = Captcha(app, default_max_rate_limit=600)\n ```\n <br>\n\n9. `default_template_dir` Arg\n\n To specify the default template_dir of all routes or endpoints use the default_template_dir arg.\n\n Example of a web page with custom template_dir:\n ```python\n captcha = Captcha(app, default_template_dir=\"/path/to/my/custom/template/directory\")\n ```\n <br>\n\n9. `verification_age` Arg\n\n Indicates the time in seconds how long a solved captcha is valid (Default: 3600 = 1 hour)\n\n Website with 3 hours verification_age:\n ```python\n captcha = Captcha(app, verification_age=10800)\n ```\n <br>\n\n9. `without_cookies` Arg\n\n If True, no cookies are created, and verification is proven via URL args (Default: False)\n\n Website with without_cookies enabled:\n ```python\n captcha = Captcha(app, without_cookies=True)\n ```\n <br>\n\n9. `block_crawler` Arg\n\n If True, crawlers like Googlebot, further are estimated via their user agent as suspicious and not the website, good for websites that should not be crawled (Default: True)\n\n Web page with block_crawler enabled:\n ```python\n captcha = Captcha(app, block_crawler=True)\n ```\n <br>\n\n9. `crawler_hints` Arg:\n\n If True, crawlers like Googlebot, are shown meta tags and the title of a normal web page, while they would have to solve a captcha. (Default: True)\n \n Web page with crawler_hints disabled:\n ```python\n captcha = Captcha(app, crawler_hints=False)\n ```\n <br>\n\n9. `third_parties` Arg:\n\n Specifies which third parties are used to check the IP addresses. By default, all 3 third parties are used. (See list)\n\n Web page that only asks a third party for Tor Ip addresses:\n ```python\n captcha = Captcha(app, third_parties=[\"tor\"])\n ```\n\n Possible entries would be:\n | Abbreviation | Who is requested and how does the evaluation mechanism work? |\n | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n | tor | [SecOps-Institute/Tor-IP-Addresses](https://raw.githubusercontent.com/SecOps-Institute/Tor-IP-Addresses/master/tor-exit-nodes.lst) on GitHub is asked for Tor Ipv4 and Ipv6 addresses and the Ip address is compared with this list |\n | ipapi | [Ipapi](https://ipapi.com) is requested with the Ip and the result of the fields \"proxy\" and \"hosting\" is used |\n | stopforumspam | [StopForumSpam](https://stopforumspam.com) is requested and the result is used |\n\n <br>\n\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Protect against bots and DDoS attacks",
"version": "1.6.7.2",
"project_urls": {
"Homepage": "https://github.com/tn3w/flask_Captchaify"
},
"split_keywords": [
"flask",
"python",
"bot",
"captcha",
"ddos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "afca9089d963ff05e976f5b419fffcec3db56aafda07f4a28de76fb808a5cf89",
"md5": "4fb677ec5c1e54c46e8c2bb9c4c6d723",
"sha256": "4b70bfd346c5dc9f7cc975d0af0748ff1b4c829ebd526d96a00e9a1d17d8c432"
},
"downloads": -1,
"filename": "flask_Captchaify-1.6.7.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4fb677ec5c1e54c46e8c2bb9c4c6d723",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 538547,
"upload_time": "2024-03-13T16:17:01",
"upload_time_iso_8601": "2024-03-13T16:17:01.285056Z",
"url": "https://files.pythonhosted.org/packages/af/ca/9089d963ff05e976f5b419fffcec3db56aafda07f4a28de76fb808a5cf89/flask_Captchaify-1.6.7.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71e495d996040b5d9f4945507079d06b3491598705c84da41740e4cbf05f00c1",
"md5": "f5641ab42020993ab467e49377c64aa8",
"sha256": "9d1814216ba8c50acb2144f5eaeb57fc7b37d145aec9f9aed43c2913c94f32db"
},
"downloads": -1,
"filename": "flask_Captchaify-1.6.7.2.tar.gz",
"has_sig": false,
"md5_digest": "f5641ab42020993ab467e49377c64aa8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 539068,
"upload_time": "2024-03-13T16:17:03",
"upload_time_iso_8601": "2024-03-13T16:17:03.151837Z",
"url": "https://files.pythonhosted.org/packages/71/e4/95d996040b5d9f4945507079d06b3491598705c84da41740e4cbf05f00c1/flask_Captchaify-1.6.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-13 16:17:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tn3w",
"github_project": "flask_Captchaify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "flask-captchaify"
}
JSON
