techaro.lol
Weighs the soul of incoming HTTP requests to stop AI crawlers
docs(user): add frequently asked questions page (#422)
Closes #400
+4
-4
docs/docs/design/how-anubis-works.mdx
+4
-4
docs/docs/design/how-anubis-works.mdx
···
37
37
ValidateChallenge -- If anything is wrong --> Fail
38
38
```
39
39
40
-
### Challenge presentation
40
+
## Challenge presentation
41
41
42
42
Anubis decides to present a challenge using this logic:
43
43
···
89
89
PresentChallenge -- Back again for another cycle --> Request
90
90
```
91
91
92
-
### Proof of passing challenges
92
+
## Proof of passing challenges
93
93
94
94
When a client passes a challenge, Anubis sets an HTTP cookie named `"within.website-x-cmd-anubis-auth"` containing a signed [JWT](https://jwt.io/) (JSON Web Token). This JWT contains the following claims:
95
95
···
102
102
103
103
This ensures that the token has enough metadata to prove that the token is valid (due to the token's signature), but also so that the server can independently prove the token is valid. This cookie is allowed to be set without triggering an EU cookie banner notification; but depending on facts and circumstances, you may wish to disclose this to your users.
104
104
105
-
### Challenge format
105
+
## Challenge format
106
106
107
107
Challenges are formed by taking some user request metadata and using that to generate a SHA-256 checksum. The following request headers are used:
108
108
···
115
115
116
116
This forms a fingerprint of the requestor using metadata that any requestor already is sending. It also uses time as an input, which is known to both the server and requestor due to the nature of linear timelines. Depending on facts and circumstances, you may wish to disclose this to your users.
117
117
118
-
### JWT signing
118
+
## JWT signing
119
119
120
120
Anubis uses an ed25519 keypair to sign the JWTs issued when challenges are passed. Anubis will generate a new ed25519 keypair every time it starts. At this time, there is no way to share this keypair between instance of Anubis, but that will be addressed in future versions.
+20
docs/docs/user/frequently-asked-questions.mdx
+20
docs/docs/user/frequently-asked-questions.mdx
···
1
+
# Frequently Asked Questions
2
+
3
+
## Why can't you just put details about the proof of work challenge into the challenge page so I don't need to run JavaScript?
4
+
5
+
A common question is something along the lines of "why can't you give me a shell script to run the challenge on my laptop so that I don't have to enable JavaScript". Malware has been known to show an interstitial that [asks the user to paste something into their run box on Windows](https://www.malwarebytes.com/blog/news/2025/03/fake-captcha-websites-hijack-your-clipboard-to-install-information-stealers), which will then make that machine a zombie in a botnet.
6
+
7
+
It would be in very bad taste to associate a security product such as Anubis with behavior similar to what malware uses. This would destroy user trust in the product and potentially result in reputational damage for the contributors. When at all possible, we want to avoid this happening.
8
+
9
+
Technically inclined users are easily able to understand how the proof of work check works by either reading the JavaScript on the page or [reading the source code of the JavaScript program](https://github.com/TecharoHQ/anubis/tree/main/web/js). Please note that the format of the challenges and the algorithms used to solve them are liable to change without notice and are not considered part of the public API of Anubis. When such a change occurs, this will break your workarounds.
10
+
11
+
If [sufficient funding is raised](https://github.com/TecharoHQ/anubis/discussions/278), a browser extension that packages the proof of work checks and looks for Anubis challenge pages to solve them will be created.
12
+
13
+
## Why does Anubis use [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) to do its proof of work challenge?
14
+
15
+
Anubis uses [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) to do its proof of work challenge for two main reasons:
16
+
17
+
1. The proof of work operation is a lot of serially blocking calls. If you do serially blocking calls in JavaScript, some browsers will hang and not respond to user input. This is bad user experience. Using a Web Worker allows the browser to do this computation in the background so your browser will not hang.
18
+
2. Web Workers allow you to do multithreaded execution of JavaScript code. This lets Anubis run its checks in parallel across all your system cores so that the challenge can complete as fast as possible. In the last decade, most CPU advancements have come from making cores and code extremely parallel. Using Web Workers lets Anubis take advantage of your hardware as much as possible so that the challenge finishes as fast as possible.
19
+
20
+
If you use a browser extension such as [JShelter](https://jshelter.org/), you will need to [modify your JShelter configuration](./known-broken-extensions.md#jshelter) to allow Anubis' proof of work computation to complete.