Update book and structure

Author: vmayoral

1_reconnaissance/README.md

@@ -0,0 +1,3 @@
+\newpage
+
+# Reconnaissance

1_reconnaissance/robot_footprinting/tutorial1/README.md

@@ -1,4 +1,6 @@
-# Footprinting ROS systems
+\newpage
+
+## Footprinting ROS systems
 
 Footprinting, (also known as *reconnaissance*) is the technique used for gathering information about digital systems and the entities they belong to. To get this information, a security analyst might use various tools and technologies. This information is very useful when performing a series attacks over an specific system.
 
@@ -21,18 +23,22 @@ docker run --privileged -it basic_cybersecurity_footprinting1:latest
 ### ROS footprinting basics
 
 The first thing we do to test the capabilities of `aztarna` is to get a container with the right dependencies and the tool installed:
+
 ~~~smallcontent
 ```bash
+
 # from this directory:
 docker build -t basic_cybersecurity_footprinting1:latest .
 ...
+
 ```
 ~~~
 
 Let's launch an instance of ROS in the default port and see how `aztarna` can detect it:
 
 ~~~smallcontent
 ```bash
+
 docker run --privileged -it basic_cybersecurity_footprinting1:latest
 root@3c22d4bbf4e1:/# roscore -p 11311 &
 root@3c22d4bbf4e1:/# roscore -p 11317 &

1_reconnaissance/robot_footprinting/tutorial2/README.md

@@ -1,4 +1,6 @@
-# Footprinting Secure ROS systems
+\newpage
+
+## Footprinting Secure ROS systems
 
 Following from the previous tutorial, in this one we'll analyze secure ROS setups using the SROS package.
 

2_robot_vulnerabilities/README.md

@@ -0,0 +1,3 @@
+\newpage
+
+# Robot vulnerabilities

2_robot_vulnerabilities/tutorial1/README.md

@@ -1,10 +1,12 @@
-# Robot sanitizers in ROS 2 Dashing
+\newpage
+
+## Robot sanitizers in ROS 2 Dashing
 
 Sanitizers are dynamic bug finding tools[1]. In this tutorial we'll use some common and open source sanitizers over the ROS 2 codebase. In particular, by reproducing previously available results[2,3], we'll review the security status of ROS 2 Dashing Diademata.
 
 The first few sections provide a walkthrough on the attempt to make things run in OS X. The sections that follow automate the process through a Docker container.
 
-## OS X
+### OS X
 
 <details><summary>Setup in OS X, natively</summary>
 
@@ -58,8 +60,8 @@ touch src/ros2/common_interfaces/trajectory_msgs/COLCON_IGNORE
 
 ```
 
-### Compile the code with sanitizers enabled (OS X)
-#### AddressSanitizer (ASan)
+#### Compile the code with sanitizers enabled (OS X)
+##### AddressSanitizer (ASan)
 For ASan[6] we compile the ROS 2 Dashing code as follows:
 ```bash
 # Get last version of FastRTPS
@@ -91,7 +93,7 @@ colcon test --build-base=build-asan --install-base=install-asan \
     --event-handlers sanitizer_report+ --packages-up-to test_communication
 ```
 
-#### ThreadSanitizer (TSan)
+##### ThreadSanitizer (TSan)
 For TSan[7] TODO
 ```bash
 # Build the code with tsan
@@ -108,8 +110,8 @@ colcon test --build-base=build-tsan --install-base=install-tsan \
     --event-handlers sanitizer_report+ --packages-up-to test_communication
 ```
 
-### Known Issues
-#### Linking issues in FastRTPS when enabling security
+#### Known Issues
+##### Linking issues in FastRTPS when enabling security
 The following happens with the version included in the Dashing Release:
 ```bash
 --- stderr: fastrtps
@@ -131,7 +133,7 @@ Failed   <<< fastrtps	[ Exited with code 2 ]
 
 Solution: install latest version of Fast-RTPS
 
-#### Results of the test indicate `Interceptors are not working. This may be because AddressSanitizer is loaded too late ... interceptors not installed`
+##### Results of the test indicate `Interceptors are not working. This may be because AddressSanitizer is loaded too late ... interceptors not installed`
 
 ```bash
 ...
@@ -159,7 +161,7 @@ DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Toolchains/Xcod
 ```
 </details>
 
-## Docker
+### Docker
 ```bash
 docker build -t basic_cybersecurity_vulnerabilities1:latest .
 docker run --privileged -it -v /tmp/log:/opt/ros2_asan_ws/log basic_cybersecurity_vulnerabilities1:latest /bin/bash
@@ -171,8 +173,8 @@ colcon test --build-base=build-asan --install-base=install-asan \
 ```
 results are under `/tmp/log`.
 
-## Analyzing results
-### Analyzing example
+### Analyzing results
+#### Analyzing example
 I'll try and analyze here the example provided at https://github.com/colcon/colcon-sanitizer-reports/blob/master/README.rst before jumping into a new one to gain additional understanding:
 
 It appears that ASan detected memory leaks in the `rcpputils` module:
@@ -226,7 +228,7 @@ Direct leak of 4 byte(s) in 1 object(s) allocated from:
 Inspecting the dumps, there seems to be an issue in `test_basic` related to `FakeGuarded::FakeGuarded()`. In particular, this [line](https://github.com/ros2/rcpputils/pull/9/files#diff-be1f2d1334d30376c4dec7b53eda0f55L247) wasn't necessary and was replaced by a destructor instead.
 
 
-### Processing new bugs
+#### Processing new bugs
 Let's now analyze a new bug and try to reason about it. Let's take the first the `sanitizer_report.csv` generated and from it, the first item (dumped at [sanitizer_report_ros2dashing_asan.csv](sanitizer_report_ros2dashing_asan.csv)):
 
 ```bash
@@ -321,7 +323,7 @@ A complete report with all the bugs found is available at [sanitizer_report_ros2
 
 A further discussion into this bug and an analysis with GDB is available at [tutorial3](../tutorial3).
 
-## Looking for bugs and vulnerabilities with ThreadSanitizer (TSan)
+### Looking for bugs and vulnerabilities with ThreadSanitizer (TSan)
 
 Similar to ASan, we can use the ThreadSanitizer:
 
@@ -335,7 +337,7 @@ A complete report with all the bugs found is available at [sanitizer_report_ros2
 
 
 
-## Resources
+### Resources
 - [1] https://arxiv.org/pdf/1806.04355.pdf
 - [2] https://discourse.ros.org/t/introducing-ros2-sanitizer-report-and-analysis/9287
 - [3] https://github.com/colcon/colcon-sanitizer-reports/blob/master/README.rst

2_robot_vulnerabilities/tutorial2/README.md

@@ -1,8 +1,10 @@
-# Robot sanitizers in MoveIt 2
+\newpage
+
+## Robot sanitizers in MoveIt 2
 
 In this tutorial we'll apply the robot santizers over the the moveit2 alpha release code and review the results. This tutorial builds on top of [tutorial1](../tutorial1/), originally inspired by [1].
 
-## Looking for bugs and vulnerabilities in MoveIt 2 with AddressSanitizer (ASan)
+### Looking for bugs and vulnerabilities in MoveIt 2 with AddressSanitizer (ASan)
 We'll dockerize the process to simplify reproduction of results. 
 Let's compile the moveit2 code with the right flags for dynamic bugs finding:
 
@@ -65,7 +67,7 @@ colcon list --packages-up-to moveit_core --topological-graph-dot | dot -Tpng -o
 
 Both, `geometric_shapes` and `moveit_core` depend on quite a few other packages so one would probably pick `octomap` for starters and try fixing that bug first scaliting into other packages.
 
-### Fixing bugs
+#### Fixing bugs
 As per the original [report](https://gist.github.com/vmayoral/25b3cff2c954b099eeb4d1471c1830e2) the `moveit_core` related bug detected by ASan is listed below:
 
 ```bash
@@ -196,7 +198,7 @@ root@bf916bb1a977:/opt/ros2_moveit2_ws# build-asan/moveit_core/planning_scene/te
 [  PASSED  ] 6 tests.
 ```
 
-## Looking for bugs and vulnerabilities in MoveIt 2 with ThreadSanitizer (TSan)
+### Looking for bugs and vulnerabilities in MoveIt 2 with ThreadSanitizer (TSan)
 
 To use TSan [3] we rebuild the container (uncommenting and commenting the right sections) access it and manually launch the tests:
 
@@ -208,7 +210,7 @@ colcon test --build-base=build-tsan --install-base=install-tsan --event-handlers
 
 No issues where found while running TSan (up until `moveit_core`).
 
-## Resources
+### Resources
 - [1] https://github.com/colcon/colcon-sanitizer-reports/blob/master/README.rst
 - [2] https://discourse.ros.org/t/exploring-package-dependencies/4719
 - [3] TSan Cpp manual https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual