goCaptcha/README.md
README.mdRaw
1# goCaptcha
2captcha server, with own datasets, to train own machine learning AI
3
4## 0 - Why?
5Captcha systems are useful to avoid bots posting data on databases. But modern captcha systems are from enterprises to train machine learning algorithms, and monetize results.
6When user answers a captcha, is training the AI from the enterprise.
7
8This project, aims to be a self hosted captcha system, that trains own AI.
9To avoid feeding AI from companies.
10
11## 1 - How to use?
12### 1.1 - Frontend
13Insert this lines in the html file:
14```html
15 <link rel="stylesheet" href="goCaptcha.css">
16
17 <div id="goCaptcha"></div>
18
19 <script>//define the url where is placed the server of goCaptcha
20 var goCaptchaURL = "http://127.0.0.1:3025";
21 </script>
22 <script src="goCaptcha.js"></script>
23```
24
25It will place the goCaptcha box in the div:
26
27
28
29### 1.2 - Backend
30- Put dataset images in the folder 'imgs'.
31- Configure serverConfig.json:
32```json
33{
34 "serverIP": "127.0.0.1",
35 "serverPort": "3025",
36 "imgsFolder": "imgs",
37 "numImgsCaptcha": 9,
38 "suspiciousIPCountLimit": 2,
39 "timeBan": 30
40}
41
42```
43
44- Run MongoDB.
45- Go to the folder /goCaptcha, and run:
46```
47./goCaptcha
48```
49It will show:
50```
51user@laptop:~/goCaptcha$ ./goCaptcha
52 goCaptcha started
53 dataset read
54 num of dataset categories: 4
55 server running
56 port: 3025
57```
58
59
60## 2 - How to make the petitions?
61
62### 2.1 - Get the captcha:
63```
64GET/ 127.0.0.1:3025/captcha
65```
66Server response:
67```json
68{
69 "id": "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
70 "imgs": [
71 "7cf6f630-e78f-469c-85dd-2d677996fea1.png",
72 "d4014318-f875-4b42-b704-4f5bf5e5e00c.png",
73 "2dd69b44-903d-4e78-bb7b-f8b07877c9e5.png",
74 "2954fc38-819d-40c9-ae3e-7b6fbb68ddbe.png",
75 "b060f58a-d44b-4e05-b466-92aa801a2aa1.png",
76 "1b838c46-b784-471e-b143-48be058c39a7.png"
77 ],
78 "question": "leopard",
79 "date": "1502274893"
80}
81```
82
83### 2.2 - User selects the images that fit in the 'question' parameter
84(in this case, 'leopard')
85
86The selection is stored in an array:
87```js
88 selection=[0,0,1,0,1,0];
89```
90Where the '1' are the images selected, in the images array order.
91
92### 2.3 - Post the answer. The answer contains the CaptchaId, and an array with the selected images
93```
94POST/ 127.0.0.1:3025/answer
95```
96Post example:
97```json
98{
99 "captchaid": "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
100 "selection": [0,0,1,0,1,0]
101}
102```
103Server response:
104```
105true
106```
107
108## 3 - How this works?
109
110### 3.1 - Server reads dataset
111First, server reads all dataset. Dataset is a directory with subdirectories, where each subdirectory contains images of one element.
112
113For example:
114```
115imgs/
116 leopard/
117 img01.png
118 img02.png
119 img03.png
120 ...
121 laptop/
122 img01.png
123 img02.png
124 ...
125 house/
126 img01.png
127 img02.png
128 ...
129```
130Then, stores all the filenames corresponding to each subdirectory. So, we have each image and to which element category is (the name of subdirectory).
131
132
133### 3.2 - Server generates captcha
134When server recieves a GET /captcha, generates a captcha, getting random images from the dataset.
135
136For each captcha generated, generates two mongodb models:
137```json
138Captcha Model
139{
140 "id" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
141 "imgs" : [
142 "7cf6f630-e78f-469c-85dd-2d677996fea1.png",
143 "d4014318-f875-4b42-b704-4f5bf5e5e00c.png",
144 "2dd69b44-903d-4e78-bb7b-f8b07877c9e5.png",
145 "2954fc38-819d-40c9-ae3e-7b6fbb68ddbe.png",
146 "b060f58a-d44b-4e05-b466-92aa801a2aa1.png",
147 "1b838c46-b784-471e-b143-48be058c39a7.png"
148 ],
149 "question" : "leopard"
150}
151```
152
153```json
154CaptchaSolution Model
155{
156 "id" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
157 "imgs" : [
158 "image_0022.jpg",
159 "image_0006.jpg",
160 "image_0050.jpg",
161 "image_0028.jpg",
162 "image_0119.jpg",
163 "image_0092.jpg"
164 ],
165 "imgssolution" : [
166 "camera",
167 "camera",
168 "laptop",
169 "crocodile",
170 "leopard",
171 "leopard"
172 ],
173 "question" : "leopard",
174 "date": "1502274893"
175}
176```
177Both models are stored in the MongoDB.
178
179The Captcha Model 'imgs' parameter, are UUIDs generated to set 'random' names to images. The server stores into MongoDB the relation between the 'random' name of each image and the real path of the image:
180```json
181{
182 "captchaid" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
183 "real" : "leopard/image_0092.jpg",
184 "fake" : "1b838c46-b784-471e-b143-48be058c39a7.png"
185}
186```
187When the server recieves a petition to get an image, recieves the petition with the fake image name, then, gets the real path of the image, gets it and serves the image content under the fake image name:
188```
189127.0.0.1:3025/image/1b838c46-b784-471e-b143-48be058c39a7.png
190```
191
192Captcha Model contains the captcha that server returns to the petition. And CaptchaSolution contains the solution of the captcha. Both have the same Id.
193
194
195### 3.3 - Server validates captcha
196When server recieves POST /answer, gets the answer, search for the CaptchaSolution based on the CaptchaId in the MongoDB, and then compares the answer 'selection' parameter with the CaptchaSolution.
197
198If the selection is correct, returns 'true', if the selection is not correct, returns 'false'.
199
200
201## 4 - Security
202
203- If the captcha is resolved in less than 1 second, it's not valid.
204- If the captcha is resolved in more than 1 minute, it's not valid.
205- The images url, are UUIDs generated each time, in order to give different names for the images each time.
206- The ip of requested captcha and answered captcha petitions must be the same.
207- Each time a user fails answering the captcha, the server adds a counter to the IP and stores in to MongoDB. When the counter on that IP is greather than the value 'suspiciousIPCountLimit' defined in serverConfig.json, the IP is blocked for 'timeBan' seconds, also defined in serverConfig.json.
208If before the counter exceeds the 'suspictiousIPCountLimit' the user answers correctly the captcha, the counter is deleted.