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