You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

314 lines
15 KiB

10 months ago
10 months ago
10 months ago
  1. ```
  2. __ _ _ _ _
  3. / _| __| | |__ ___ _ __ (_) __| | ___ _ __
  4. | |_ / _` | '_ \ _____/ __| '_ \| |/ _` |/ _ | '__|
  5. | _| (_| | |_) |_____\__ | |_) | | (_| | __| |
  6. |_| \__,_|_.__/ |___| .__/|_|\__,_|\___|_|
  7. |_|
  8. ```
  9. 1. [Introduction](#introduction)
  10. 2. [Installation](#installation)
  11. 3. [Usage](#usage)
  12. * [Configuration File Syntax](#configuration-file-syntax)
  13. * [Efficient Xpath Copying](#efficient-xpath-copying)
  14. * [Step By Step Guide](#step-by-step-guide)
  15. - [var domain](#var-domain)
  16. - [var entry list](#var-entry-list)
  17. - [var link and iteration](#var-link-and-iteration)
  18. - [example1 link](#example1-link)
  19. - [example2 link](#example2-link)
  20. - [javascript](#javascript)
  21. - [var jsdomain](#var-jsdomain)
  22. - [vars jslink and jsiteration](#vars-jslink-and-jsiteration)
  23. - [example1 jslink and jsiteration](#example1-jslink-and-jsiteration)
  24. - [display](#display)
  25. - [another tip](#another-tip)
  26. - [var parent](#var-parent)
  27. - [example1 parent](#example1-parent)
  28. - [vars children](#vars-children)
  29. - [var slow downloading](#var-slow-downloading)
  30. # Introduction
  31. The fdb-spider was made to gather data from Websites in an automated way.
  32. The Website to be spidered has to be a list of Links.
  33. Which makes the fdb-spider a web spider for most Plattforms.
  34. The fdb-spider is to be configured in a .yaml file to make things easy.
  35. The output of the fdb-spider is in json format to make it easy to input
  36. the json to other programs.
  37. At its core, the spider outputs tag search based entries
  38. It works together with the fdb-spider-interface.
  39. In Future, the spider will be extended by the model Sauerkraut.
  40. An !open source! Artificial Neural Network.
  41. # Installation
  42. FIRST install systemwide requirements with your package manager
  43. ```
  44. # apt based unixoids
  45. apt install xvfb
  46. apt install chromium
  47. apt install chromium-webdriver
  48. # pacman based unixoids
  49. pacman -S xorg-server-xvfb
  50. pacman -S xorg-server-xephyr
  51. pacman -S chromium
  52. ```
  53. THEN create a python3 virtualenv on your favourite UNIX Distribution
  54. with the command
  55. ```
  56. git clone https://code.basabuuka.org/alpcentaur/fdb-spider
  57. cd fdb-spider
  58. virtualenv venv
  59. source venv/bin/activate
  60. pip install -r requirements.txt
  61. ```
  62. # Usage
  63. ## Configuration File Syntax
  64. The configuration file with working syntax template is
  65. ```
  66. /spiders/config.yaml
  67. ```
  68. Here you can configure new websites to spider, referred to as "databases".
  69. link1 and link2 are the links to be iterated.
  70. The assumption is, that every list of links will have a loopable structure.
  71. If links are javascript links, specify js[domain,link[1,2],iteration-var-list].
  72. Otherwise leave them out, but specify jsdomain as 'None'.
  73. You will find parents and children of the entry list pages.
  74. Here you have to fill in the xpath of the entries to be parsed.
  75. In the entry directive, you have to specify uniform to either TRUE or FALSE.
  76. Set it to TRUE, if all the entry pages have the same template, and you
  77. are able to specify xpath again to get the text or whatever variable you
  78. like to specify.
  79. In the entry_unitrue directive, you can specify new dimensions and
  80. the json will adapt to your wishes.
  81. Under the entry-list directive this feature has to be still implemented.
  82. So use name, link, javascript-link, info, period and sponsor by commenting
  83. in or out.
  84. If javascript-link is set (which means its javascript clickable),
  85. link will be ignored.
  86. Set it to FALSE, if you have diverse pages behind the entries,
  87. and want to generally get the main text of all the different links.
  88. For your information, the library trafilature is used to gather the
  89. text generally for further processing.
  90. ## Efficient Xpath Copying
  91. When copying the Xpath, most modern Webbrowsers are of help.
  92. In Firefox (or Browsers build on it like the TOR Browser) you can use
  93. ```
  94. strl-shift-c
  95. ```
  96. to open the "Inspector" in "Pick an element" mode.
  97. When you click on the desired entry on the page,
  98. it opens the actual code of the clicked element in the html search box.
  99. Now make a right click on the code in the html search box, go on "Copy",
  100. and go on XPath.
  101. Now you have the XPath of the element in your clipboard.
  102. When pasting it into the config, try to replace some slashes with double
  103. slashes. That will make the spider more stable, in case the websites
  104. html/xml gets changed for maintenance or other reasons.
  105. ## Step By Step Guide
  106. Start with an old Configuration that is similar to what you need.
  107. There are Three Types of Configurations:
  108. The first Type is purely path based. An example is greenjobs.de.
  109. The second Type is a mixture of path and javascript functions, giz is an example for this Type.
  110. The third Type is purely javascript based. An example is ted.europe.eu.
  111. Type 1:
  112. Start with collecting every variable.
  113. From up to down.
  114. ### var domain
  115. domain is the variable for the root of the website.
  116. In case links are glued, they will be glued based on the root.
  117. ### var entry list
  118. Now come all the variables regarding the entry list pages.
  119. #### var link and iteration
  120. In Pseudo Code, whats happening with these three variables is
  121. ```
  122. for n in iteration var list:
  123. get(link1 glued to n glued to link2)
  124. ```
  125. So if you are on the no javascript side of reality, you are lucky. Thats all needed to get the collection of links.
  126. #### example1 link
  127. Lets say we go on greenjobs.de.
  128. We go on search without search query. To get the biggest displayed output, in best case a table of everything the site has listed.
  129. https://www.greenjobs.de/angebote/index.html?s=&loc=&countrycode=de&dist=10&lng=&lat=
  130. is the resulting url.
  131. So now we navigate through the pages.
  132. In this case everything is displayed and scrollable on exactly this url. Which means, we leave link2 and iteration var list empty. And put the resulting url into link1.
  133. #### example2 link
  134. This time we go on giz. There we have https://ausschreibungen.giz.de/Satellite/company/welcome.do as our url for a general search. If I go on the "nextpage" button of the displayed table, a new url pattern appears being on the next page:
  135. https://ausschreibungen.giz.de/Satellite/company/welcome.do?method=showTable&fromSearch=1&tableSortPROJECT_RESULT=2&tableSortAttributePROJECT_RESULT=publicationDate&selectedTablePagePROJECT_RESULT=2
  136. Going on the next side again, we get the url:
  137. https://ausschreibungen.giz.de/Satellite/company/welcome.do?method=showTable&fromSearch=1&tableSortPROJECT_RESULT=2&tableSortAttributePROJECT_RESULT=publicationDate&selectedTablePagePROJECT_RESULT=3
  138. So now we already see the pattern, that any and every machine generated output cant hide.
  139. RSULT=1 .... we put it in the url bar of the browser
  140. https://ausschreibungen.giz.de/Satellite/company/welcome.do?method=showTable&fromSearch=1&tableSortPROJECT_RESULT=2&tableSortAttributePROJECT_RESULT=publicationDate&selectedTablePagePROJECT_RESULT=1
  141. and get to the first pages.
  142. Which leads to the following variables, considering that there were 6 pages:
  143. * link1 = "https://ausschreibungen.giz.de/Satellite/company/welcome.do?method=showTable&fromSearch=1&tableSortPROJECT_RESULT=2&tableSortAttributePROJECT_RESULT=publicationDate&selectedTablePagePROJECT_RESULT="
  144. * link2 = ""
  145. * iteration-var-list = "[1,2,3,4,5,6]"
  146. #### javascript
  147. It happens, that it is not possible to see a pattern in the urls. Probably because the website hoster is not smart or just a thief in a bad sense. In this case you only get html gibberish. To get the desired info with the help of this program, you have the possibility to give the config.yaml paths of clickable items. The spider will open an axctual browser and click through the pages that start to exist.
  148. #### var jsdomain
  149. If jsdomain is "None" (And here it is important to use None and not NONE), it will try to get the domains and download elements based on the gets with a variety of libraries.
  150. But if you have a javascript situation, where the first html are already javascript generated kaos without xml to parse.. then you need to put an url here. By putting the url, the spider will open that website with a virtual graphical browser (using selenium), wait for the javascript to load, and by clicking on jslink, go through the pages.
  151. In pseudo code that means, if you fill out the variable jsdomain in the config.yaml, the spider will do
  152. ```
  153. for i in jsiteration-var-list:
  154. click on the jslink string glued to i glued to jslink2
  155. ```
  156. #### vars jslink and jsiteration
  157. In jslink1 and jslink2 you have to put the xpath of the button that clicks to the next site of entry links to download.
  158. Sometimes the xpath changes, after the new js content got loaded. That is where the jsiteration-var-list comes in. And like this, you define the button that gets klicked every site. Sometimes it stays the same, then you just need an occurence of the same number exactly the same times as in the var-iteration, which will define how many pages will be downloaded generally. The var iteration-var-list defines the folder structure of the json output files.
  159. Which means we emulate a whole virtual "user" using a virtual "browser" on his or her virtual "screen". In the end the clickable elements are defined by xpath too, so put these accordingly in the jslink and jsiteration variables.
  160. You can run the spider with display=1 instead of display=0 in the python line of the virtual display the chromium driver is running on. I will put that in the initialization of the spider. How to do this, in general if you use any of the js related variables instead of setting "NONE" (important: and not "None"), will be described in the paragraph display. It is very useful to debug js related configs.
  161. With running the spider while watching the automated mouse moves and clicks, you will be able to find the right xpath for every step and element.
  162. #### example1 jslink and jsiteration
  163. So let us consider evergabe-online as an example.
  164. ```
  165. evergabe-online:
  166. domain: 'https://www.evergabe-online.de/'
  167. entry-list:
  168. link1: 'https://www.evergabe-online.de/search.html?101-1.-searchPanel>
  169. link2: '-pageLink'
  170. jsdomain: 'https://www.evergabe-online.de/search.html'
  171. jslink1: '/html/body/div[8]/main/div[4]/div/div/div[2]/table/thead/tr[1]/td/div[2]/div/span['
  172. jslink2: ']'
  173. jsiteration-var-list: "[1,2, 3, 4, 5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6]
  174. iteration-var-list: "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
  175. ```
  176. Go on jsdomain https://www.evergabe-online.de/search.html.
  177. You will see the table we want to spider.
  178. Open the inspector, and have a look at the button to get to the next site.
  179. Its xpath is '/html/body/div[8]/main/div[4]/div/div/div[2]/table/thead/tr[1]/td/div[2]/div/span[1]'
  180. Now we click on it. On page two, the button to click us to page three has the xpath:
  181. '/html/body/div[8]/main/div[4]/div/div/div[2]/table/thead/tr[1]/td/div[2]/div/span[2]'
  182. From page 5 on, the button to get to the next pages stays
  183. '/html/body/div[8]/main/div[4]/div/div/div[2]/table/thead/tr[1]/td/div[2]/div/span[6]'
  184. until the end.
  185. #### display
  186. When you run the spider with js spidering enabled, in fdb_spider.py a display will get created. If you open nano, and press crtl+w, you can type display and enter. This will bring you to the lines of code, generating the display.
  187. Watch out for the line
  188. ```
  189. display = Display(visible=0, size=(1200, 800))
  190. ```
  191. If you change visible=0 to visible=1 here, the spider will run with actually open a viewable browser on the workspace.
  192. This line is present two times in the code. One for downloading the pages with the links, and one for downloading the pages of/behind the links.
  193. After finding and jumping to "display" with ctrl-w, go down some lines, and issue ctrl-w again. Or find out in the manual how to jump to the next occurance, I knew it once.
  194. #### another tip
  195. In main.py, where the spiders code gets loaded, you have also a function available called
  196. ```
  197. spider.find_config_parameter(list_of_fdbs)
  198. ```
  199. This function helps you to find the right config parameters, because it shows you what you get. That can be a bit tricky, because if you get nothing, it does not really help you. But when you have the first ones running, it shows you exactly that: That its always possible and no magic needed.
  200. #### var parent
  201. The parent stands for the last xml element which contains the entry links. Go with the Inspector on the entry respectively one of the links, klick on it and klick in the code view afterwards. Now use the arrow up key to get to the last child before it comes to the parent. You can see it on the rendered html blue contained.
  202. From the last child, when it is selected in the code view of the Inspector, do a left click on it.
  203. Select copy --> full xpath.
  204. Now copy paste the xpath to the parent variable, and put a double slash in front of the last element in the route.
  205. #### example1 parent
  206. For the List of the Gesellschaft für internationale Zusammenarbeit the last child before the parent is
  207. //html//body//div//div//table[contains(@class, 'csx-new-table')]//tbody//tr
  208. a tr which kind of stands for row in html. This, because GIZ is cooperative and ordered. You need the //tr because that says "search for any tr" which means we are reffering to a list of elements.
  209. #### vars children
  210. for the children it is about to define in xpath syntax, where the text lies that we want to be parsed automatically. child-name, child-link, child-period, child-info and child-sponsor are defined until now.
  211. In future it will be possible to define any variables anywhere and get that fed into the json output.
  212. #### var javascript link
  213. In case the whole website to spider is javascript generated gibberish, there is another possibility for you. To find out if the website is generated gibberish not containing your payload, just search in the outputed pages for the child name etc. If you do not find them, or directly see on the html pages no real xml, try to download your sites with jsdomain, and go up again to the paragraphs before. For the actual link child, the spider can javascript style clicking download the htmls behind the links already while downloading the entry list htmls with javascript.
  214. For that to happen, you can define the javascript link that needs to be clicked in xpath syntax. If it becomes a pop up, which source code needs to be processed, or if it becomes an actual page the source code will be parsed, or if the clickable link refers to a pdf, the spider will handle all situations and output the resulting text in json under spiders/output.
  215. #### var slow downlading
  216. slow downloading comes into take when a website uses lazy loading and / or is used by too many users resulting in loading very slow. In this case, the selenium part, as any normal user, runs into problems of timing. Which leads to much longer processing time, when harvesting the lists. Depending on the configuration of the firewall of the server you are harvesting, there may even be a limit by time. And again, we just can act as a lot of different instances and everyone just gets a part of it to download. In this sense, even for future totalitarist system that may come, the freeing of information from big platforms is always and will always be possible in peer to peer systems.