What is this?
Fixes #479
Add any further explanations here.
TODO
- [x] Make pyinstaller bootloader launch custom C code
- [x] Create C file that would communicate with island on Windows
- [x] FIX #528
- [x] Create C file that would communicate with island on Linux
- [x] Make island recognize an display machines where bootloader communicated, but monkey did not
- [ ] Refactor pyinstaller alterations into a patch, which we can apply to any incoming new pyinstaller version
- [ ] Alter deployment script to include bootloader and pyinstaller dev version with patch
- [ ] Test on OS compat env
TDD
Prerequisites
Old machine bootloader program is incorporated into pyinstaller bootloader. Pyinstaller bootloader is the first thing that starts when a built monkey is launched, thus our code is launched before monkey and has access to monkey flags. This allows us to write code that would inspect the current machine and send requests to island directly or via tunnel and decide to continue with launching monkey code or to quit.
This is a multilevel problem so TDD is separated into these sections that represent corresponding layers:
- Bootloader program
- Connections and tunneling
- Island server and data gathered
- Data representation
Bootloader program
How to setup bootloader development env.
We have pyinstaller forks, one for linux and one for windows. Pull them and get relevant bootloader dev env.
To update pyinstaller we'll have to pull from pyinstaller git, merge and rebuild pyinstaller bootloader. Then do a release and add built pyinstaller bootloader.
To update bootloader we'll have to push to our forks and rebuild pyinstaller bootloader. Then do a release and add built pyinstaller bootloader.
Monkey build process
Building the monkey will require custom pyinstaller bootloader binary. Depending on OS this binary should be downloaded from our pyinstaller for release and placed into a pyinstaller install folder. Maybe this can be automated via deployment scripts.
Bootloader program workflow
- Monkey binary is ran.
- Bootloader starts and parses monkey flags to extract tunnel and server.
- Bootloader collects information about system: OS, IP, Hostname.
- Bootloader looks at current OS info and determines whether to run the monkey or to quit after it finishes.
- Bootloader changes server port from x to x+1 OR we can have a dedicated flag.
- Bootloader forms http request with OS, IP, Hostname and will monkey be ran info.
- Bootloader sends HTTP request where a proxy server is listening.
- If bootloader didn't get proper response it tries to use tunnel.
Connections and tunneling
Monkey
Tunneling on monkey is expanded to tunnel http traffic.
Island
Island starts a basic http server on a separate thread. It connects to the mongodb and gets port to serve on. It's either island's port +1 or a dedicated config value. When this HTTP proxy server gets a request it passes it to the /api/bootloader
endpoint on the main server and also forwards back the response.
Island server and data gathered
Island receives data on an api/bootloader
endpoint and stores it on a separate collection. Each bootloader telemetry has the following fields: OS, IP list, Hostname and if monkey will be run. Upon receiving bootloader telemetry island finds and updates bootloader_state
variable on corresponding node.
bootloader_state
can be one of three values:
- Bottloader didn't run (default)
- Bootloader ran, monkey will run ( if
monkey_will_run
value is True in bootloader telem )
- Bootloader ran, monkey will not run ( if
monkey_will_run
value is False in bootloader telem )
Data representation
Map
States of node will be the following:
- Scanned node (
exploited: False
bootloader_state: not_started
on node)
- Exploited node (
exploited: True
bootloader_state: not_started
on node)
- Machine too old (
exploited: True
bootloader_state: monkey_won't_run
on node)
OR
- Monkey will run (
exploited: True
bootloader_state: monkey_will_run
on node)
- Monkey is running.
- Monkey died.
To recap 2 states with corresponding UI will be added: Machine too old to run monkey and Monkey will run.
Report
When generating report island will query mongodb to find if there are any entries of bootloader telemetry with bootloader_state: monkey_won't_run
. If so, outdated machine issue is generated.
Testing
Bootloader binary
Manual tests on some old windows and linux machines. Also, on some new ones.
Tunneling
Windows machine will be added to tunneling env in monkeyzoo. New blackbox test will run tunneling test as usual, but will also verify that each bootloader communicated with island.
Data gathering and UI
Tested manually
Dev. env. deployment
This feature changes development environment in the following way:
- We need custom pyinstaller bootloader to build monkeys
So deployment scripts will have to be altered to do:
- Download pyinstaller bootloader from our pyinstaller fork release
- Replace default bootloader in pyinstaller folder
Feature