more text, toc resturctured

parent 9f39d74c
Pipeline #19572724 passed with stage
in 18 minutes and 38 seconds
......@@ -3,7 +3,20 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Failmap Documentation 🤣
Failmap End User Documentation
========================
.. toctree::
:maxdepth: 2
:caption: Contents:
topics/scanning_policy
topics/faq_end_users
topics/user_guide
topics/running_a_remote_worker
topics/thanks
Failmap Developer Documentation
========================
.. toctree::
......@@ -12,21 +25,15 @@ Failmap Documentation 🤣
topics/getting_started
topics/development
topics/scanners_scanning_and_rating
topics/running_a_remote_worker
topics/deployment
topics/data_model
topics/translation
topics/deployment
topics/gis_and_map_information
topics/writing_a_scanner
topics/stacking_pattern
topics/docker
topics/task_processing_system
topics/user_guide
topics/scanning_policy
topics/thanks
topics/stacking_pattern
Indices and tables
......
# Administration
This is a short manual to help with administration of information in the admin interface.
## Getting started
The admin interface is located on https://admin.faalkaart.nl/admin/, to visit this you
need a failmap certificate, which you can obtain from the development team. They can also
help you obtaining or resetting a (your) password.
It is recommended to have a few windows open while administrating:
- Admin interface: https://admin.faalkaart.nl/admin/
- Issues: https://gitlab.com/failmap/tickets/issues/
- Chat: https://gitter.im/internet-cleanup-foundation/
## Overview
The Failmap Admin inteface is a classic "CRUD" (Create Read Update Delete) interface directly
on top of the django ORM, close to the database. As such the presentation contains a lot of fields.
## When encountering bugs / need features
Please create an issue here: https://gitlab.com/failmap/failmap/issues
## Admin Actions
Admin actions make it easier to run scanners. They are visible at the bottom of lists.
![admin actions](administration/admin_actions.png)
### Scan Plain HTTP
Scans for lack of HTTPS. If there is only HTTP and no HTTPS on the standard ports, this will show a high risk issues.
### Scan Security Headers
Scans for HTTP server headers. Results in medium and low risk issues.
### Scan TLS Qualys
Runs a TLS scan
### Rebuild Rating
### Onboard
### Subdomains (Certificate Transparency)
### Subdomains (NSEC)
### Discover HTTP(S) Endpoints
### Create Screenshot
Doesn't work.
### Declare dead
## (advanced) debugging issues
Grafana can be useful to see that "scan tasks" are running when issued.
- Grafana: https://grafana.faalkaart.nl/dashboard/db/tasks?orgId=1&from=now-5m&to=now&refresh=10s
Using Sentry, it's possible to see if there where crashes in any of the scanners:
- Sentry: https://sentry.io/internet-cleanup-foundation/faalkaart/
Server access (server managers only):
```bash
ssh -A user@faalserver.faalkaart.nl
sudo su -
journalctl -u docker-failmap-<tab><tab>
or
journalctl -f -u docker-failmap*
failmap-logtail
```
This will allow you to see the output of running services.
If all else fails, run a failmap locally and view it's output.
# History
## These texts are kept for historical purposes.
Many organizations (have to) transfer sensitive information over the internet. Sometimes they ask to share sensitive
information with them via forms, mail and etcetera. Anyone should be able to use internet services without worrying
their information is being altered or changed, whether unintentionally or malicious. Many responsible organizations
boast about their capability (so called "cyber") to protect.
Failmap adds an enormous amount of transparency. This is the driving force for many organizations to change / clean up
their online presence. With the launch of failmap, thousands of issues have been fixed in the Netherlands,
just because they have been made understandable and publicly accessible (naming and shaming).
We display the "base level" of security, which can be illustrative of the the quality and capability of organizations
in protecting your data. The base level are issues that are well documented and there are dozens of online web-services
that can discover these issues for years now. Might we find more severe vulnerabilities, we employ (and endorse)
Responsible Disclosure to address them: they will not ever be published (as that goes against our mission to increase
safety and trust).
The transparent, tendentious, and shaming approach has had a lot of impact in the Netherlands, where the tool has
become a must have for many municipalities. It's not all tendentious though: organizations strive to be "green" on the
map and they are given free reports on what was wrong, with pointers to public sources such as OWASP to help them
improve their services.
## What do the scores mean?
Failmap knows five colors:
- Green / Yellow: nothing that we scan is wrong
- Orange: there are some slicht issues, that need addressing
- Red: there are more severe compromises in the base level of security
- Gray: Unkown
## My organization is shown Red / Orange, now what?
Read the report on the bottom of the page to see what's wrong and how to fix it. When in doubt, read our scanning policy
to learn some specific quirks and features of our scanners.
An organization only needs one "high" issues to become red, as security is as strong as it's weakest link.
## My organization is completely green, has it won?
It's certainly an impressive feat, most of the time.
Unfortunately scanning only holds up for creating a baseline. The organization might still offer services that we
cannot (or will not) verify automatically. Such as outdated software, logic flaws and so on.
## How complete is failmap?
Failmap automatically scans the internet for subdomains of domains. This creates an enormous catalog of URL's that are
associated with organizations. However, failmap does only scan the "base level" of security and there might be many
domains of subdomains of organization we miss.
In the Netherlands, just for municipalities, we scan about 8000 endpoints daily or weekly.
We add all subdomains given to our e-mail address: info@faalkaart.nl
## The score is wrong / I've improved my stuff! Please rescan.
Rescanning for most issues happens daily, some weekly. See our scanning policy for more information.
If you think we're still reporting the wrong things, please use the "incorrect finding" button in the report to send
an e-mail to our service desk. Our service desk may be slow, but it might even result in software updates, policy
improvements and more.
Our goal is to accurately show the state of "base level" security: we're also not happy when things are displayed inaccurately.
## How to implement TLS correctly?
There are many tutorials online to do so. The Dutch Cert (Nationaal Cyber Security Centrum) has great general advice and
policies how to do so. Other governemental organizations (IBD for Dutch Municipalities for example) also provide fact
sheets and support.
The website Cipher List also shows a lot of config defaults for many services: https://cipherli.st/
## Since when did failmap start to annoy people?
March 2016 the first beta was written in PHP in a single days, for the "in het hoofd van de hacker" conference.
## Can i run my own failmap?
Yes, the source of failmap is open and can be used non-commercially.
# Available scanners
## Supported scans
| Scan | Port(s) | IPv Support | Protocols | Rate limit | Rotation |
| :------------------ | :---------- | :---------- | :-------- | :--------- | :--------- |
| DNS | A/AAAA | - | DNS | No | Not yet automated |
| Endpoint discovery | Defaults | 4 | http(s) | No | Per 3 days |
| TLS (qualys) | 443 | 4, 6 | TLS | 1/minute | Per 3 days |
| Headers | Any http(s) | 4 | http(s) | No | Daily |
| Screenshots | Any http(s) | 4 | http(s) | 1 thread | Not yet automated |
| Plain HTTPS | Any http(s) | 4 | http(s) | No | Daily |
| DNSSEC | - | - | DNS | No | Daily |
### DNS
The DNS scanner tries to find hostnames using various strategies:
- Brute force on a subdomain list (existing subdomains only)
- Looking at NSEC1 hashes
- Looking at Certificate transparency
Less popular, not fully automated, but also implemented:
- brute forcing dictionaries
- looking in search engines
### Endpoint Discovery
Tries to find HTTP(s) endpoints on standard HTTP(s) ports. A normal website currently has about four endpoints:
- IPv6 port 80, redirect to port 443
- IPv6 port 443, actual website
- IPv4 port 80, redirect to port 443
- IPv4 port 443, actual website
We store them separately as implementation mistakes might occur on any of these endpoints.
### TLS (qualys)
Runs a scan on ssllabs from Qualys and incorporates the result.
### Headers
Contacts an endpoint and verifies HTTP headers for various security settings. (HSTS etc)
### Screenshots
Uses chrome headless to contact a website and make a screenshot for it. This screenshow it displayed next to the results
in the report.
### Plain HTTPS
Checks if a website that only has a site on port 80 also has a secure equivalent. No port-80-only sites should exist.
### DNSSEC
Checks if the toplevel domain implements DNSSEC correctly. Uses the dotSE scanner which is included.
## Scheduling
Scanners are scheduled as periodic tasks in Django admin. They are disabled by default and might not all be included in
the source distribution. Creating a scan is actually easy. For example:
- General/Name: discover-endpoints
- General/Enabled: Yes
- General/Task: discover-endpoints
- Schedule/Interval: every 3 days
- Arguments/Arguments: ["failmap.scanners.scanner_http"]
- Execution Options/Queue: storage
## Manual scans
### Command line
The Scan command can help you:
```bash
failmap scan 'scanner name'
```
The message returned will tell you what scanners you can run manually. All scanners have the same set of options.
### Admin interface
It's possible to run manual scans, at the bottom of a selection.
Note that this is beta functionality and please don't do this too much as the "priority" scanning queue is not functioning.
You can try out a scan or two, some take a lot of time.
![admin_actions](scanners_scanning_and_ratings/admin_actions.png)
## Manual scans
### Command line
The Scan command can help you:
```bash
failmap scan 'scanner name'
```
The message returned will tell you what scanners you can run manually. All scanners have the same set of options.
### Admin interface
It's possible to run manual scans, at the bottom of a selection.
Note that this is beta functionality and please don't do this too much as the "priority" scanning queue is not functioning.
You can try out a scan or two, some take a lot of time.
![admin_actions](scanners_scanning_and_ratings/admin_actions.png)
These texts are stored for archival purposes. They have been removed from the website in order to save people from
translating stuff that is already in the manual.
# Welke grote veranderingen zijn er geweest?
December 2017
Lijsten met recente updates toegevoegd.
1500 urls toegevoegd.
November 2017
Grafieken van kwetsbaarheden toegevoegd.
Scores vervangen door absolute faal voor meer duidelijkheid.
Beter opvolgen van redirects (feedback).
6 november: livegang nieuwe versie faalkaart.
Oktober 2017
Scan op het ontbreken van TLS toegevoegd.
Scores tussen 0 (geen vermelding), 200 en 1000.
Scan op HTTP Headers toegevoegd, waaronder HSTS.
Scores tussen 0 en 200.
Enkele duizenden domeinen toegevoegd.
Januari 2017
Scanners hebben enkele maanden op pauze gestaan.
Juni 2016
Nieuwe TLS kwetsbaarheid: veel rood.
Maart 2016
Introductie faalkaart, 1800 domeinen.
Scores tussen 0 tot en met 1000.
# Wat is de historie van Faalkaart?
**28 augustus 2017**: Er wordt op een nieuwe manier beoordeeld. Per beveiligingsfout worden punten uitgedeeld. Heeft een organisatie geen punten, dan hebben we geen fouten kunnen vinden: perfect! Er is nu dus ook een top win!
In deze update is de kaartsoftware bijgewerkt: er wordt nu gebruik gemaakt van open streetmaps, beter kaartmateriaal, het django python framework, dynamische javascripts en betere caching. De site laadt niet alleen sneller, hij is beter te onderhouden. Alle ontwikkeling van de faalkaart gebeurd inmiddels open source. Patches zijn welkom.
Al het werk levert ook wat nieuwe features op: deze site wordt automatisch ververst als je de site open laat staan, het is mogelijk om door de tijd heen te scrollen en er is nu een top 50 van meest falende organisaties. In plaats van afzonderlijke sites te kijken, wordt er nu per organisatie beoordeeld. Tenslotte hebben we alle sites die niet meteen TLS spreken aangemerkt als een "gemiddelde" fout: in de vorige versie van de kaart werd hier nog geen oordeel over gegeven. Het ontbreken van TLS is net zo erg als slechte TLS.
**15 februari 2017**: Inmiddels wordt er weer [volop gewerkt](https://github.com/failmap) aan faalkaart. De kaart is bijgewerkt naar nieuwe, goed onderhoudbare, technieken. Inmiddels is er een [stichting opgericht](https://internetcleanup.foundation) om de ontwikkeling van de kaart te stimuleren. Binnenkort wordt er gewerkt aan het beter scannen van e.e.a: er gaat meer en sneller gescand worden.
**7 augustus 2016**: Faalkaart heeft de steun gekregen van het SIDN fonds, we zullen het komende jaar de kaart uitbreiden en op veel meer controleren. We gaan de kaartrot oplossen en zorgen dat het makkelijk wordt om zelf de kaart te kunnen draaien (onafhankelijk). Ook is de chaching van de site ingevoerd, dus het voelt weer snel(ler) aan.
**9 juni 2016**: Door een nieuwe kwetsbaarheid zijn er 100+ domeinen in het rood beland, van 2% naar 9% kwetsbaar dus. Het aantal matige domeinen blijft gelukkig afnemen. Hoe lang zal het duren tot alles gepatched is? Wie patcht het laatst?
**Extra update**: Faalkaart heeft een projectbijdrage gevraagd aan het SIDN fonds om er voor te zorgen dat dit middel breder en makkelijker kan worden ingezet. We gaan hierdoor vele honderdduizenden kwetsbaarheden aan de kaak te stellen en blijven motiveren om ze te verhelpen. De techneuten, hackers en nerds achter faalkaart staan te trappelen om het internet robuuster te maken. Half Juni weten we meer. Spannend!
**Extra update 2**: We zien dat door de grote hoeveelheid data we caching moeten gaan toepassen en verder moeten optimaliseren. De bedoeling is om de kaart zo actueel mogelijk weer te geven. Tot dit opgelost is zal het iets langer duren voordat de kaart geladen is.
**8 april 2016**: Het aantal domeinen met een onvoldoende is gezakt naar 2%, was ooit 8%. Er zijn zojuist 1200 domeinen toegevoegd. Er is een team aan het ontstaan dat de faalkaart verder gaat uitbreiden en onderhouden. Vele handen maken licht werk. Dank aan gemeenten voor het insturen van subdomeinen. Dit is altijd welkom!
**25 maart 2016**: De kaart wordt automatisch ververst. Onder de uitleg staat een overzicht met domeinen die onvoldoende scoren.
**18 maart 2016**: De kaart wordt zeer binnenkort automatisch bijgewerkt. Nieuw zijn statistieken met historie. De domeinenlijst is verbeterd en er is tekst toegevoegd over de totstandkoming van het cijfer. Binnenkort ook open source.
**16 maart 2016**: De eerste serie van 1800 domeinen is geladen, dit wordt nog aangevuld en zal binnenkort opnieuw worden gecontroleerd. De testdatum is nu zichtbaar. De eerste verbeteringen schijnen een half uur na presentatie al te zijn doorgevoerd. Dat is stoer!
\ No newline at end of file
......@@ -2,7 +2,6 @@
Failmap tries to scan with all scanners every day. This means the map shows new results on a daily basis.
## What does failmap scan?
Failmap scans the following:
......@@ -16,13 +15,22 @@ Daily scans:
Weekly scans:
- New subdomains (using various methods)
- Subdomain discovery
- TLS quality using Qualys SSL Labs
Not all scans are published and a variety of scans will be implemented in the coming weeks.
**Subdomain discovery**
The DNS scanner tries to find hostnames using various strategies:
- Brute force on a subdomain list (existing, targeted subdomains only)
- Looking at NSEC1 hashes
- Looking at the Certificate transparency database
**Endpoint discovery**
Failmap tries to auto-discover endpoints for urls. A normal website today has about four endpoints:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment