Merge pull request #78 from alasjo/package-refactor

Python package - refactor

.gitignore

@@ -1,5 +1,164 @@
-tool/.idea/
-.idea/
+# Custom
 *~
-*.pyc
 *.hex
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+*.idea/

README.md

@@ -1,43 +1,41 @@
 # Caring Caribou
-A friendly car security exploration tool
+A friendly automotive security exploration tool.
 
 ## Rationale
-We are lacking a security testing tool for automotive. A zero-knowledge tool that can be dropped onto any CAN network and collect information regarding what services and vulnerabilities exist. This is a start.
-
 This work was initiated as part of the research project HEAVENS (HEAling Vulnerabilities to ENhance Software Security and Safety), but lives on as a stand-alone project.
+We were lacking a security testing tool for automotive; a zero-knowledge tool that can be dropped onto any CAN network and collect information regarding what services and vulnerabilities exist. This project is a start.
 
-## How to install
-Instructions available [here](documentation/howtoinstall.md)
-
-## Troubleshooting
-See common errors and solutions [here](documentation/troubleshooting.md)
+## Documentation
+- [How to install](documentation/howtoinstall.md)
+- [How to use](documentation/howtouse.md)
+- [Troubleshooting](documentation/troubleshooting.md), common errors and solutions
 
-## How to use
-The best way to understand how to use Caring Caribou is to look at the help screen:
+## Get started
+Install the tool:
 
-    python cc.py -h
+    python setup.py install
 
-or simply
+The best way to understand how to use Caring Caribou is to look at the help screen:
 
-    ./cc.py -h
+    cc.py --help
 
 This will list all available modules at the bottom of the output. Help for specific modules works the same way. For example, the help screen for the `send` module is shown by running
 
-    ./cc.py send -h
+    cc.py send --help
 
 The module help always includes some usage examples. If the module has multiple sub functions, these have similar help screens as well:
 
-    ./cc.py send message -h
-    ./cc.py send file -h
+    cc.py send message -h
+    cc.py send file -h
 
-More detailed usage information is available [here](https://github.com/CaringCaribou/caringcaribou/blob/master/documentation/howtouse.md).
+More detailed usage information is available [in the documentation on usage](documentation/howtouse.md).
 
 ## Features and Architecture
-Caring Caribou is based on a master script `cc.py`, which runs the show. This enables an easy drop-in architecture for new modules, which are located in the `/modules` folder.
+Caring Caribou is based on a main entry point, `cc.py`, which runs the show. This enables an easy drop-in architecture for new modules, which are located in the `caringcaribou/modules` folder.
 
-The `/lib` folder contains various higher level CAN protocol implementations and shared functions, meant to be used by modules.
+The `caringcaribou/utils` folder contains various higher level CAN protocol implementations and shared functions, meant to be used by modules.
 
-The `/tests` folder contains automated test suites and `/documentation` stores module documentation files.
+The `caringcaribou/tests` folder contains automated test suites and `/documentation` stores documentation files (modules are also documented here).
 
 ## List of Modules
 A clean installation of Caring Caribou includes the following modules:
@@ -110,8 +108,8 @@ Discovers and utilizes various ISO 13400-2 services.
 
 Details here: [doip module](documentation/doip.md)
 
-## List of libraries
-The `/lib` folder contains the following libraries:
+## List of libraries/utilities
+The `caringcaribou/utils` folder contains the following:
 
 ### can_actions.py
 Provides abstraction for access to the CAN bus, bruteforce engines etc.
@@ -136,12 +134,16 @@ Some sort of CAN bus interface (http://elinux.org/CAN_Bus#CAN_Support_in_Linux)
 - python-can
 - a pretty modern linux kernel
 
-## Extending the project
-Create a python file with a function `module_main(args)` and put it in the ```tool/modules``` folder. Caring Caribou will automagically recognize it as a module and list it in the output of `./cc.py -h`
+## Extending the project with new modules
+- A template for new modules is available in `caringcaribou/modules/module_template.py`
+- Create a python file with a function `module_main(args)` (or copy the template) in the `caringcaribou/modules` directory.
+- In `setup.py`, add an entry under `caringcaribou.modules`, referencing your new module like: `my_module = caringcaribou.modules.my_module`
+- Run `python setup.py install`
+- Verify that the module is available, should be listed in the output of `cc.py -h`
 
-For example, if your new module is located in `modules/foo.py` you run it with the command `./cc.py foo`. Additional arguments (if any) are passed as arguments to the `module_main` function.
+If your new module is located in `caringcaribou/modules/foo.py` you will run it with the command `cc.py foo`.
+Additional arguments (if any) are passed as arguments to the `module_main` function.
 
-A template for new modules is available in `tool/template`
 
 ## The target
 The target ECU used for the development setup is an STM32F107 based dev-board from ArcCore called Arctic EVK-M3, but the tool can be used against any ECU communicating over a CAN bus.
@@ -162,3 +164,4 @@ The target ECU used for the development setup is an STM32F107 based dev-board fr
 * FearfulSpoon
 * Alex DeTrano
 * Thomas Sermpinis
+* Alexander Alasjö