octopus/README.md

OCTOPUS
---

Samuel AUBERTIN - EURECOM - 2022

![SPECTRE Octopus Logo](logo.png "SPECTRE Octopus Logo")

**OCTOPUS** is a [Spectre](https://spectreattack.com/spectre.pdf) V1 (_Bounds Check Bypass_) + V2 (_Branch Target Injection_) vulnerabilty tester.

It measures and uploads the success rate of the Spectre attacks on your CPU using different compilers:

- [GCC](https://gcc.gnu.org/)
- [Clang](https://clang.llvm.org/)

And compilation/linking flags such as:

- Optimisation levels (```-O```)
- Static/dynamic linking
- [Masking](https://github.com/torvalds/linux/blob/cb6416592bc2a8b731dabcec0d63cda270764fc6/arch/x86/include/asm/barrier.h#L27) and [lfence](https://www.intel.com/content/www/us/en/developer/articles/troubleshooting/using-intel-compilers-to-mitigate-speculative-execution-side-channel-issues.html) mitigations against Spectre V1
- [RETPOLINE](https://support.google.com/faqs/answer/7625886) mitigation against Spectre V2

It is known to work on the following _GNU/Linux_ distributions : _Alpine_, _RHEL8_, _Fedora35_. and _OpenBSD_.

## Results

Results are stored as JSON objects in an unique file for each run, following this pattern: ```result-$(UUID).json```

## Dependencies

- Compiler: ```clang``` and ```gcc```
- Linker: ```lld```
- For upload: ```openssh``` and ```uuid```
- The C library static symbols: ```glibc-static```

## Execution

Will build, execute and upload the results.

```make```

### Build only 

```make build```

To build using multiple processes:

```make [-j XXX] build``` where ```XXX``` is the number of parallel processes.

## Results aggregation

Results are automatically uploaded to a server with a dedicated account using ```sftp```.

Here is an exhaustive list of the data sent:
- CPU model name and microcode version.
- Kernel version and compilation date.
- GCC and clang versions.
- The list of mitigations enabled at runtime.
- The cache timings of the processor computed by the ```calibrate_threshold()``` function.
- Each spectre execution success rate.

**NONE** of this data will be used for anyhting else except this experiment.

## References

Both implementations are heavily inspired by:

- [ErikAugust gist](https://gist.github.com/ErikAugust/724d4a969fb2c6ae1bbd7b2a9e3d4bb6)
- [genua GmbH PoC](https://github.com/genua/meltdown)