issue #7: provide tutorial

[noxdafox]

First three chapters.

Tested locally.

Signed-off-by: Matteo Cafasso [email protected]

[noxdafox]

Last chapter has been added. PR in review.

[Wenzel]

When i tried to generate the documentation with Sphinx, i got the following warnings :

Running Sphinx v1.5.1
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 12 source files that are out of date
updating environment: 12 added, 0 changed, 0 removed
reading sources... [  8%] developer
reading sources... [ 16%] index
reading sources... [ 25%] installation
reading sources... [ 33%] setup
reading sources... [ 41%] tutorial_conclusions
reading sources... [ 50%] tutorial_hellomalware
reading sources... [ 58%] tutorial_hellosandbox
reading sources... [ 66%] tutorial_injection
reading sources... [ 75%] tutorial_installation
reading sources... [ 83%] tutorial_plugins
reading sources... [ 91%] tutorial_setup
reading sources... [100%] user

/tmp/see/doc/installation.rst:34: ERROR: Unexpected indentation.
/tmp/see/doc/installation.rst:35: WARNING: Block quote ends without a blank line; unexpected unindent.
/tmp/see/doc/installation.rst:41: ERROR: Unexpected indentation.
/tmp/see/doc/installation.rst:42: WARNING: Block quote ends without a blank line; unexpected unindent.
/tmp/see/doc/installation.rst:52: ERROR: Unexpected indentation.
/tmp/see/doc/installation.rst:54: WARNING: Block quote ends without a blank line; unexpected unindent.
/tmp/see/doc/installation.rst:57: ERROR: Unexpected indentation.
/tmp/see/doc/installation.rst:59: WARNING: Block quote ends without a blank line; unexpected unindent.
/tmp/see/doc/installation.rst:69: ERROR: Unexpected indentation.
/tmp/see/doc/installation.rst:70: WARNING: Block quote ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /tmp/see/doc/installation.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [  8%] developer
writing output... [ 16%] index
writing output... [ 25%] installation
writing output... [ 33%] setup
writing output... [ 41%] tutorial_conclusions
writing output... [ 50%] tutorial_hellomalware
writing output... [ 58%] tutorial_hellosandbox
writing output... [ 66%] tutorial_injection
writing output... [ 75%] tutorial_installation
writing output... [ 83%] tutorial_plugins
writing output... [ 91%] tutorial_setup
writing output... [100%] user

generating indices... genindex
writing additional pages... search
copying images... [100%] sample.png

copying static files... WARNING: html_static_path entry '/tmp/see/doc/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 12 warnings.

I don't know if they are relevant, yet you might want to fix them.

[noxdafox]

removed the unused installation.rst file

[noxdafox]

@Wenzel any further comment? Shall I merge?

[Wenzel]

My comments for the Installation section:

1. Why do you start by this sentence ?
   Please refer to the installation documentation if problems are encountered.

It should be at the end of this section, when the user has indeed tried to install see.
Also the link points to the libvirt installation page. I expect it to point to a more complete and accurate documentation about see's installation.

2. These Debian packages are not strictly necessary. They are required in the Tutorial’s last chapters.
not strictly necessary -> optional ?
   It's easier to understand what something is, rather than what it is not.

3. About vminspect, you can drop a quick description and a link to the github page

4. # pip3 install python-see
   The only way to use see is to install a python package system wide, from pip ?
   Is there another solution ?
   Maybe you should provide a Dockerfile if there is no other way, because i don't want to mess with my system python packages to try a software.

5. The following command allows to add a user to a group. # adduser <username> <group>
   I tend to prefer using usermod -a -G group1,group2 user to modify a user's group list, than adduser,
   since you just want to modify and not create a new account.

6. To verify that KVM is available it is enough to run
   Here you are loading the kvm modules.
   either kvm is installed and the modules are loaded, or it is not installed, but i never had to load them manually.
   If you want to test if kvm is available, it's easier to just run:
   lsmod | grep kvm_intel\|kvm_amd

[noxdafox]

1,2,3 will fix.

4: The python package is the correct way to install SEE. It's up to the user to choose how and where to install the package. The tutorial is about the framework not how to set up a generic development environment. Docker in particular, does not play well with SEE.

5: the commands are equivalent, I'd rather stick to the one already used in the documentation.

6: the fact that you never had to load KVM in an OS doesn't mean it's loaded by default on all the distributions. The command will exit with 0 if the loading was successful or it was already loaded, it will prompt an error if KVM is not supported by the HW.

[Wenzel]

Also in the Plugins and Protocols section:

• Refer to the Documetation to see how -> Documentation

That's all, you can merge it 👍

[noxdafox]

@Wenzel it seems the "previous"/"next" links are not supported by the theme.

sphinx-doc/alabaster#18

I'll see if I can somehow workaround this.

[noxdafox]

Seems only supported way atm is via side bar: http://alabaster.readthedocs.io/en/latest/customization.html#variables-and-feature-toggles