Weighs the soul of incoming HTTP requests to stop AI crawlers
11
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: add BotStopper docs from the git repo (#752)

Signed-off-by: Xe Iaso <me@xeiaso.net>

authored by

Xe Iaso and committed by
GitHub
d7a758f8 c121896f

+222
+7
.github/actions/spelling/expect.txt
··· 20 20 berr 21 21 bingbot 22 22 bitcoin 23 + bitrate 23 24 blogging 24 25 Bluesky 25 26 blueskybot 26 27 boi 27 28 botnet 29 + botstopper 28 30 BPort 29 31 Brightbot 30 32 broked ··· 52 54 cloudflare 53 55 Codespaces 54 56 confd 57 + connnection 55 58 containerbuild 56 59 coreutils 57 60 Cotoyogi ··· 93 96 Factset 94 97 fastcgi 95 98 fediverse 99 + ffprobe 96 100 finfos 97 101 Firecrawl 98 102 flagenv ··· 199 203 openai 200 204 opengraph 201 205 openrc 206 + oswald 202 207 pag 203 208 palemoon 204 209 Pangu ··· 272 277 tagline 273 278 tarballs 274 279 tarrif 280 + tbn 281 + tbr 275 282 techaro 276 283 techarohq 277 284 templ
+215
docs/docs/admin/botstopper.mdx
··· 1 + --- 2 + title: "Commercial support and an unbranded version" 3 + --- 4 + 5 + If you want to use Anubis but organizational policies prevent you from using the branding that the open source project ships, we offer a commercial version of Anubis named BotStopper. BotStopper builds off of the open source core of Anubis and offers organizations more control over the branding, including but not limited to: 6 + 7 + - Custom images for different states of the challenge process (in process, success, failure) 8 + - Custom CSS and fonts 9 + - Custom titles for the challenge and error pages 10 + - "Anubis" replaced with "BotStopper" across the UI 11 + - A private bug tracker for issues 12 + 13 + In the near future this will expand to: 14 + 15 + - A private challenge implementation that does advanced fingerprinting to check if the client is a genuine browser or not 16 + - Advanced fingerprinting via [Thoth-based advanced checks](./thoth.mdx) 17 + 18 + In order to sign up for BotStopper, please do one of the following: 19 + 20 + - Sign up [on GitHub Sponsors](https://github.com/sponsors/Xe) at the $50 per month tier or higher 21 + - Email [sales@techaro.lol](mailto:sales@techaro.lol) with your requirements for invoicing, please note that custom invoicing will cost more than using GitHub Sponsors for understandable overhead reasons 22 + 23 + ## Installation 24 + 25 + Install BotStopper like you would Anubis, but replace the image reference. EG: 26 + 27 + ```diff 28 + -ghcr.io/techarohq/anubis:latest 29 + +ghcr.io/techarohq/botstopper/anubis:latest 30 + ``` 31 + 32 + ### Binary packages 33 + 34 + Binary packages are available [in the GitHub Releases page](https://github.com/TecharoHQ/botstopper/releases), the main difference is that the package name is `techaro-botstopper`, the systemd service is `techaro-botstopper@your-instance.service`, the binary is `/usr/bin/botstopper`, and the configuration is in `/etc/techaro-botstopper`. All other instructions in the [native package install guide](./native-install.mdx) apply. 35 + 36 + ### Docker / Podman 37 + 38 + In order to pull the BotStopper image, you need to [authenticate with GitHub's Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). 39 + 40 + ```text 41 + docker login ghcr.io -u your-username --password-stdin 42 + ``` 43 + 44 + Then you can use the image as normal. 45 + 46 + ### Kubernetes 47 + 48 + If you are using Kubernetes, you will need to create an image pull secret: 49 + 50 + ```text 51 + kubectl create secret docker-registry \ 52 + techarohq-botstopper \ 53 + --docker-server ghcr.io \ 54 + --docker-username your-username \ 55 + --docker-password your-access-token \ 56 + --docker-email your@email.address 57 + ``` 58 + 59 + Then attach it to your Deployment: 60 + 61 + ```diff 62 + spec: 63 + securityContext: 64 + fsGroup: 1000 65 + + imagePullSecrets: 66 + + - name: techarohq-botstopper 67 + ``` 68 + 69 + ## Configuration 70 + 71 + ### Docker compose 72 + 73 + Follow [the upstream Docker compose directions](https://anubis.techaro.lol/docs/admin/environments/docker-compose) with the following additional options: 74 + 75 + ```diff 76 + anubis: 77 + image: ghcr.io/techarohq/botstopper/anubis:latest 78 + environment: 79 + BIND: ":8080" 80 + DIFFICULTY: "4" 81 + METRICS_BIND: ":9090" 82 + SERVE_ROBOTS_TXT: "true" 83 + TARGET: "http://nginx" 84 + OG_PASSTHROUGH: "true" 85 + OG_EXPIRY_TIME: "24h" 86 + 87 + + # botstopper config here 88 + + CHALLENGE_TITLE: "Doing math for your connnection!" 89 + + ERROR_TITLE: "Something went wrong!" 90 + + OVERLAY_FOLDER: /assets 91 + + volumes: 92 + + - "./your_folder:/assets" 93 + ``` 94 + 95 + #### Example 96 + 97 + There is an example in [docker-compose.yaml](https://github.com/TecharoHQ/botstopper/blob/main/docker-compose.yaml). Start the example with `docker compose up`: 98 + 99 + ```text 100 + docker compose up -d 101 + ``` 102 + 103 + And then open [https://botstopper.local.cetacean.club:8443](https://botstopper.local.cetacean.club:8443) in your browser. 104 + 105 + > [!NOTE] 106 + > This uses locally signed sacrificial TLS certificates stored in `./demo/pki`. Your browser will rightly reject these. Here is what the example looks like: 107 + > 108 + > ![](/img/botstopper/example-screenshot.webp) 109 + 110 + ## Custom images and CSS 111 + 112 + Anubis uses an internal filesystem that contains CSS, JavaScript, and images. The BotStopper variant of Anubis lets you specify an overlay folder with the environment variable `OVERLAY_FOLDER`. The contents of this folder will be overlaid on top of Anubis' internal filesystem, allowing you to easily customize the images and CSS. 113 + 114 + Your directory tree should look like this, assuming your data is in `./your_folder`: 115 + 116 + ```text 117 + ./your_folder 118 + └── static 119 + ├── css 120 + │ └── custom.css 121 + └── img 122 + ├── happy.webp 123 + ├── pensive.webp 124 + └── reject.webp 125 + ``` 126 + 127 + For an example directory tree using some off-the-shelf images the Tango icon set, see the [testdata](https://github.com/TecharoHQ/botstopper/tree/main/testdata/static/img) folder. 128 + 129 + ### Custom CSS 130 + 131 + CSS customization is done mainly with CSS variables. View [the example custom CSS file](https://github.com/TecharoHQ/botstopper/blob/main/testdata/static/css/custom.css) for more information about what can be customized. 132 + 133 + ### Custom fonts 134 + 135 + If you want to add custom fonts, copy the `woff2` files alongside your `custom.css` file and then include them with the [`@font-face` CSS at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face): 136 + 137 + ```css 138 + @font-face { 139 + font-family: "Oswald"; 140 + font-style: normal; 141 + font-weight: 200 900; 142 + font-display: swap; 143 + src: url("./fonts/oswald.woff2") format("woff2"); 144 + } 145 + ``` 146 + 147 + Then adjust your CSS variables accordingly: 148 + 149 + ```css 150 + :root { 151 + --body-sans-font: Oswald, sans-serif; 152 + --body-preformatted-font: monospace; 153 + --body-title-font: serif; 154 + } 155 + ``` 156 + 157 + To convert `.ttf` fonts to [Web-optimized woff2 fonts](https://www.w3.org/TR/WOFF2/), use the `woff2_compress` command from the `woff2` or `woff2-tools` package: 158 + 159 + ```console 160 + $ woff2_compress oswald.ttf 161 + Processing oswald.ttf => oswald.woff2 162 + Compressed 159517 to 70469. 163 + ``` 164 + 165 + Then you can import and use it as normal. 166 + 167 + ### Customizing images 168 + 169 + Anubis uses three images to visually communicate the state of the program. These are: 170 + 171 + | Image name | Intended message | Example | 172 + | :------------- | :----------------------------------------------- | :-------------------------------- | 173 + | `happy.webp` | You have passed validation, all is good | ![](/img/botstopper/happy.webp) | 174 + | `pensive.webp` | Checking is running, hold steady until it's done | ![](/img/botstopper/pensive.webp) | 175 + | `reject.webp` | Something went wrong, this is a terminal state | ![](/img/botstopper/reject.webp) | 176 + 177 + To make your own images at the optimal quality, use the following ffmpeg command: 178 + 179 + ```text 180 + ffmpeg -i /path/to/image -vf scale=-1:384 happy.webp 181 + ``` 182 + 183 + `ffprobe` should report something like this on the generated images: 184 + 185 + ```text 186 + Input #0, webp_pipe, from 'happy.webp': 187 + Duration: N/A, bitrate: N/A 188 + Stream #0:0: Video: webp, none, 25 fps, 25 tbr, 25 tbn 189 + ``` 190 + 191 + In testing 384 by 384 pixels gives the best balance between filesize, quality, and clarity. 192 + 193 + ```text 194 + $ du -hs * 195 + 4.0K happy.webp 196 + 12K pensive.webp 197 + 8.0K reject.webp 198 + ``` 199 + 200 + ## Customizing messages 201 + 202 + You can customize messages using the following environment variables: 203 + 204 + | Message | Environment variable | Default | 205 + | :------------------- | :------------------- | :----------------------------------------- | 206 + | Challenge page title | `CHALLENGE_TITLE` | `Ensuring the security of your connection` | 207 + | Error page title | `ERROR_TITLE` | `Error` | 208 + 209 + For example: 210 + 211 + ```sh 212 + # /etc/techaro-botstopper/gitea.env 213 + CHALLENGE_TITLE="Wait a moment please!" 214 + ERROR_TITLE="Client error" 215 + ```
docs/static/img/botstopper/example-screenshot.webp

This is a binary file and will not be displayed.

docs/static/img/botstopper/happy.webp

This is a binary file and will not be displayed.

docs/static/img/botstopper/pensive.webp

This is a binary file and will not be displayed.

docs/static/img/botstopper/reject.webp

This is a binary file and will not be displayed.