aboutsummaryrefslogtreecommitdiff
path: root/docker/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'docker/README.md')
-rw-r--r--docker/README.md75
1 files changed, 74 insertions, 1 deletions
diff --git a/docker/README.md b/docker/README.md
index 7558954..8475813 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -34,13 +34,86 @@ Generate the new manylinux wheel from the `tosa_checker` wheel:
```console
auditwheel repair dist/<tosa_checker>.whl -w dist/
```
-The `tosa_checker` manylinux wheel can now be found in the `/dist` directory.
+The `tosa_checker` manylinux wheel can now be found in the `dist/` directory.
Install the `tosa_checker` manylinux wheel:
```console
pip install dist/<tosa_checker-manyliux>.whl
```
+## How to use the TOSA Checker Docker™ image with security countermeasures
+
+A Docker™ image is provided for builds of the TOSA Checker with security countermeasures
+that are used in the project's continuous integration system. The following countermeasures are provided
+in this image:
+
+* [Address Sanitizer (ASAN)](https://clang.llvm.org/docs/AddressSanitizer.html)
+* [Undefined Behavior Sanitizer (UBSAN)](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
+* [Bandit](https://pypi.org/project/bandit/)
+
+This section will explain how to use this Docker™ image to build the TOSA checker with
+sanitizers and lint the Python source code with Bandit.
+
+### Building the TOSA Checker with sanitizers
+To build the Docker™ image run the command below:
+
+```console
+docker build . -t tc-cp39-countermeasures --build-arg PYTHON_VERSION=3.9 -f CI.Dockerfile
+```
+
+*Note: In this example, the image is built with Python 3.9. This can be changed using the PYTHON_VERSION argument.*
+
+After this, run the container as follows, mounting the source code to the container:
+
+```console
+docker run -it -v <tosa_checker source code on your machine>:/tosa_checker tc-cp39-countermeasures
+```
+
+Following this, build the TOSA checker using the following command:
+
+```console
+cd tosa_checker
+python3.9 setup.py --tensorflow_src_dir /tensorflow_src --sanitizer <sanitizer option> bdist_wheel
+```
+Choose between `asan` or `ubsan` as the sanitizer option. The `tosa_checker` wheel can be found in the `dist/` directory.
+
+The TOSA Checker wheel can then be installed as follows:
+
+```console
+python3.9 -m pip install dist/<tosa_checker>.whl
+```
+
+To then run the unit test of the TOSA Checker, the requirements for this must be installed:
+
+```console
+cd tests
+python3.9 -m pip install -r requirements.txt
+```
+
+Then, if you're using the ASAN option:
+```console
+export LD_PRELOAD=$(clang -print-file-name=libclang_rt.asan-x86_64.so)
+ASAN_OPTIONS=detect_leaks=0 python3.9 -m pytest --capture=no .
+```
+
+For the UBSAN option, run the following command:
+```console
+UBSAN_OPTIONS=print_stacktrace=1 python3.9 -m pytest --capture=no .
+```
+
+### Running the Bandit linter
+Firstly build and run the Docker™ image:
+```console
+docker build . -t tc-cp39-countermeasures --build-arg PYTHON_VERSION=3.9 -f CI.Dockerfile
+docker run -it -v <tosa_checker source code on your machine>:/tosa_checker tc-cp39-countermeasures
+```
+
+After this, a HTML report can be generated with Bandit as follows:
+```console
+cd tosa_checker
+python3.9 -m bandit --configfile .bandit.yaml -r . -f html -o report.html
+```
+
## Trademarks and Copyrights
* Python® is a registered trademark of the PSF.