oxbrbtx/PrimAITE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merged PR 104: Fix formatting in docstrings

Browse Source 
## Summary
Fixes some incorrectly formatted documentations, such as in the observation module. Also adds some missing module-level docstrings. Also adds a PrimAITE Favicon to docs.

Removed Primaite-dependencies.rst as it's autogenerated.

## Test process
Purely cosmetic, so functionality not tested. I did render the HTML output to observe that some mistakes have been fixed.

## Checklist
- [x] This PR is linked to a **work item**
- [x] I have performed **self-review** of the code
- [na] I have written **tests** for any new functionality added with this PR
- [x] I have updated the **documentation** if this PR changes or adds functionality
- [ ] I have run **pre-commit** checks for code style

Related work items: #1572
This commit is contained in:
Marek Wolan
2023-07-10 08:14:08 +00:00
parent 677d12b550 91287f8666
commit 47d7e9f3f6
48 changed files with 232 additions and 569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -140,6 +140,7 @@ cython_debug/
# IDE # IDE
.idea/ .idea/
docs/source/primaite-dependencies.rst
# outputs # outputs
src/primaite/outputs/ src/primaite/outputs/

0
docs/_static/.gitkeep vendored Normal file
View File

2
docs/_templates/custom-class-template.rst vendored
View File

@@ -9,7 +9,7 @@
:members: :members:
:show-inheritance: :show-inheritance:
:inherited-members: :inherited-members:
:special-members: __call__, __add__, __mul__ :special-members: __init__, __call__, __add__, __mul__
{% block methods %} {% block methods %}
{% if methods %} {% if methods %}

1
docs/index.rst
View File

@@ -43,6 +43,7 @@ The best place to start is :ref:`about`
:caption: Project Links: :caption: Project Links:
:hidden: :hidden:
..
#Code <> #Code <>
#Issues <> #Issues <>
#Pull Requests <> #Pull Requests <>

429
docs/source/primaite-dependencies.rst
View File

@@ -1,429 +0,0 @@
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Name | Version | License | URL |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Babel | 2.12.1 | BSD License | https://babel.pocoo.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| GPUtil | 1.4.0 | MIT | https://github.com/anderskm/gputil |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Gymnasium | 0.26.3 | MIT | https://gymnasium.farama.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Jinja2 | 3.1.2 | BSD License | https://palletsprojects.com/p/jinja/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Markdown | 3.4.3 | BSD License | https://Python-Markdown.github.io/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| MarkupSafe | 2.1.2 | BSD License | https://palletsprojects.com/p/markupsafe/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Pillow | 9.5.0 | Historical Permission Notice and Disclaimer (HPND) | https://python-pillow.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| PyWavelets | 1.4.1 | MIT License | https://github.com/PyWavelets/pywt |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| PyYAML | 6.0 | MIT License | https://pyyaml.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Pygments | 2.15.1 | BSD License | https://pygments.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Send2Trash | 1.8.2 | BSD License | https://github.com/arsenetar/send2trash |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Sphinx | 6.1.3 | BSD License | https://www.sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| Werkzeug | 2.3.4 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| absl-py | 1.4.0 | Apache Software License | https://github.com/abseil/abseil-py |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| aiofiles | 22.1.0 | Apache Software License | https://github.com/Tinche/aiofiles |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| aiosignal | 1.3.1 | Apache Software License | https://github.com/aio-libs/aiosignal |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| aiosqlite | 0.19.0 | MIT License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| alabaster | 0.7.13 | BSD License | https://alabaster.readthedocs.io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| anyio | 3.7.0 | MIT License | https://anyio.readthedocs.io/en/stable/versionhistory.html |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| argon2-cffi | 21.3.0 | MIT License | https://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| argon2-cffi-bindings | 21.2.0 | MIT License | https://github.com/hynek/argon2-cffi-bindings |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| arrow | 1.2.3 | Apache Software License | https://arrow.readthedocs.io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| asttokens | 2.2.1 | Apache 2.0 | https://github.com/gristlabs/asttokens |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| astunparse | 1.6.3 | BSD License | https://github.com/simonpercivall/astunparse |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| attrs | 23.1.0 | MIT License | https://www.attrs.org/en/stable/changelog.html |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| backcall | 0.2.0 | BSD License | https://github.com/takluyver/backcall |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| beautifulsoup4 | 4.12.2 | MIT License | https://www.crummy.com/software/BeautifulSoup/bs4/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| bleach | 6.0.0 | Apache Software License | https://github.com/mozilla/bleach |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| build | 0.10.0 | MIT License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| cachetools | 5.3.0 | MIT License | https://github.com/tkem/cachetools/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| certifi | 2023.5.7 | Mozilla Public License 2.0 (MPL 2.0) | https://github.com/certifi/python-certifi |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| cffi | 1.15.1 | MIT License | http://cffi.readthedocs.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| cfgv | 3.3.1 | MIT License | https://github.com/asottile/cfgv |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| charset-normalizer | 3.1.0 | MIT License | https://github.com/Ousret/charset_normalizer |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| click | 8.1.3 | BSD License | https://palletsprojects.com/p/click/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| cloudpickle | 2.2.1 | BSD License | https://github.com/cloudpipe/cloudpickle |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| colorama | 0.4.6 | BSD License | https://github.com/tartley/colorama |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| comm | 0.1.3 | BSD License | https://github.com/ipython/comm |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| contourpy | 1.0.7 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| coverage | 7.2.6 | Apache Software License | https://github.com/nedbat/coveragepy |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| cycler | 0.11.0 | BSD License | https://github.com/matplotlib/cycler |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| debugpy | 1.6.7 | Eclipse Public License 2.0 (EPL-2.0); MIT License | https://aka.ms/debugpy |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| decorator | 5.1.1 | BSD License | https://github.com/micheles/decorator |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| defusedxml | 0.7.1 | Python Software Foundation License | https://github.com/tiran/defusedxml |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| distlib | 0.3.6 | Python Software Foundation License | https://github.com/pypa/distlib |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| dm-tree | 0.1.8 | Apache Software License | https://github.com/deepmind/tree |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| docutils | 0.19 | BSD License; GNU General Public License (GPL); Public Domain; Python Software Foundation License | https://docutils.sourceforge.io/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| exceptiongroup | 1.1.1 | MIT License | https://github.com/agronholm/exceptiongroup/blob/main/CHANGES.rst |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| executing | 1.2.0 | MIT License | https://github.com/alexmojaki/executing |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| fastjsonschema | 2.17.1 | BSD License | https://github.com/horejsek/python-fastjsonschema |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| filelock | 3.12.0 | The Unlicense (Unlicense) | https://github.com/tox-dev/py-filelock |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| flake8 | 6.0.0 | MIT License | https://github.com/pycqa/flake8 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| flatbuffers | 23.5.26 | Apache Software License | https://google.github.io/flatbuffers/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| fonttools | 4.39.4 | MIT License | http://github.com/fonttools/fonttools |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| fqdn | 1.5.1 | Mozilla Public License 2.0 (MPL 2.0) | https://github.com/ypcrts/fqdn |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| frozenlist | 1.3.3 | Apache Software License | https://github.com/aio-libs/frozenlist |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| furo | 2023.3.27 | MIT License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| gast | 0.4.0 | BSD License | https://github.com/serge-sans-paille/gast/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| google-auth | 2.19.0 | Apache Software License | https://github.com/googleapis/google-auth-library-python |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| google-auth-oauthlib | 0.4.6 | Apache Software License | https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| google-pasta | 0.2.0 | Apache Software License | https://github.com/google/pasta |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| grpcio | 1.51.3 | Apache Software License | https://grpc.io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| gym | 0.21.0 | UNKNOWN | https://github.com/openai/gym |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| gymnasium-notices | 0.0.1 | MIT License | https://github.com/Farama-Foundation/gym-notices |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| h5py | 3.9.0 | BSD License | https://www.h5py.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| identify | 2.5.24 | MIT License | https://github.com/pre-commit/identify |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| idna | 3.4 | BSD License | https://github.com/kjd/idna |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| imageio | 2.29.0 | BSD License | https://github.com/imageio/imageio |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| imagesize | 1.4.1 | MIT License | https://github.com/shibukawa/imagesize_py |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| importlib-metadata | 4.13.0 | Apache Software License | https://github.com/python/importlib_metadata |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| iniconfig | 2.0.0 | MIT License | https://github.com/pytest-dev/iniconfig |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ipykernel | 6.23.1 | BSD License | https://ipython.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ipython | 8.13.2 | BSD License | https://ipython.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ipython-genutils | 0.2.0 | BSD License | http://ipython.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| isoduration | 20.11.0 | ISC License (ISCL) | https://github.com/bolsote/isoduration |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jax | 0.4.12 | Apache-2.0 | https://github.com/google/jax |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jedi | 0.18.2 | MIT License | https://github.com/davidhalter/jedi |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| json5 | 0.9.14 | Apache Software License | https://github.com/dpranke/pyjson5 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jsonpointer | 2.3 | BSD License | https://github.com/stefankoegl/python-json-pointer |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jsonschema | 4.17.3 | MIT License | https://github.com/python-jsonschema/jsonschema |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter-events | 0.6.3 | BSD License | http://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter-server | 1.24.0 | BSD License | https://jupyter-server.readthedocs.io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter-ydoc | 0.2.4 | BSD 3-Clause License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter_client | 8.2.0 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter_core | 5.3.0 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter_server_fileid | 0.9.0 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter_server_terminals | 0.4.4 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyter_server_ydoc | 0.6.1 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyterlab | 3.6.1 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyterlab-pygments | 0.2.2 | BSD | https://github.com/jupyterlab/jupyterlab_pygments |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| jupyterlab_server | 2.22.1 | BSD License | https://jupyterlab-server.readthedocs.io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| keras | 2.12.0 | Apache Software License | https://keras.io/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| kiwisolver | 1.4.4 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| lazy_loader | 0.2 | BSD License | https://github.com/scientific-python/lazy_loader |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| libclang | 16.0.0 | Apache Software License | https://github.com/sighingnow/libclang |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| lz4 | 4.3.2 | BSD License | https://github.com/python-lz4/python-lz4 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| markdown-it-py | 2.2.0 | MIT License | https://github.com/executablebooks/markdown-it-py |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| matplotlib | 3.7.1 | Python Software Foundation License | https://matplotlib.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| matplotlib-inline | 0.1.6 | BSD 3-Clause | https://github.com/ipython/matplotlib-inline |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| mavizstyle | 1.0.0 | UNKNOWN | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| mccabe | 0.7.0 | MIT License | https://github.com/pycqa/mccabe |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| mdurl | 0.1.2 | MIT License | https://github.com/executablebooks/mdurl |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| mistune | 2.0.5 | BSD License | https://github.com/lepture/mistune |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ml-dtypes | 0.2.0 | Apache Software License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| mock | 5.0.2 | BSD License | http://mock.readthedocs.org/en/latest/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| mpmath | 1.3.0 | BSD License | http://mpmath.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| msgpack | 1.0.5 | Apache Software License | https://msgpack.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| nbclassic | 0.5.6 | BSD License | https://github.com/jupyter/nbclassic |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| nbclient | 0.8.0 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| nbconvert | 7.4.0 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| nbformat | 5.9.0 | BSD License | https://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| nest-asyncio | 1.5.6 | BSD License | https://github.com/erdewit/nest_asyncio |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| networkx | 3.1 | BSD License | https://networkx.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| nodeenv | 1.8.0 | BSD License | https://github.com/ekalinin/nodeenv |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| notebook | 6.5.4 | BSD License | http://jupyter.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| notebook_shim | 0.2.3 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| numpy | 1.23.5 | BSD License | https://www.numpy.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| oauthlib | 3.2.2 | BSD License | https://github.com/oauthlib/oauthlib |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| opt-einsum | 3.3.0 | MIT | https://github.com/dgasmith/opt_einsum |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| overrides | 7.3.1 | Apache License, Version 2.0 | https://github.com/mkorpela/overrides |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| packaging | 23.1 | Apache Software License; BSD License | https://github.com/pypa/packaging |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pandas | 2.0.1 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pandocfilters | 1.5.0 | BSD License | http://github.com/jgm/pandocfilters |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| parso | 0.8.3 | MIT License | https://github.com/davidhalter/parso |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pickleshare | 0.7.5 | MIT License | https://github.com/pickleshare/pickleshare |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| platformdirs | 3.5.1 | MIT License | https://github.com/platformdirs/platformdirs |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| plotly | 5.15.0 | MIT License | https://plotly.com/python/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pluggy | 1.0.0 | MIT License | https://github.com/pytest-dev/pluggy |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pre-commit | 2.20.0 | MIT License | https://github.com/pre-commit/pre-commit |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| primaite | 2.0.0rc1 | GFX | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| primaite | 2.0.0rc1 | GFX | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| primaite | 2.0.0rc1 | GFX | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| prometheus-client | 0.17.0 | Apache Software License | https://github.com/prometheus/client_python |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| prompt-toolkit | 3.0.38 | BSD License | https://github.com/prompt-toolkit/python-prompt-toolkit |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| protobuf | 3.20.3 | BSD-3-Clause | https://developers.google.com/protocol-buffers/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| psutil | 5.9.5 | BSD License | https://github.com/giampaolo/psutil |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pure-eval | 0.2.2 | MIT License | http://github.com/alexmojaki/pure_eval |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyasn1 | 0.5.0 | BSD License | https://github.com/pyasn1/pyasn1 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyasn1-modules | 0.3.0 | BSD License | https://github.com/pyasn1/pyasn1-modules |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pycodestyle | 2.10.0 | MIT License | https://pycodestyle.pycqa.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pycparser | 2.21 | BSD License | https://github.com/eliben/pycparser |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyflakes | 3.0.1 | MIT License | https://github.com/PyCQA/pyflakes |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyparsing | 3.0.9 | MIT License | https://github.com/pyparsing/pyparsing/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyproject_hooks | 1.0.0 | MIT License | https://github.com/pypa/pyproject-hooks |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyrsistent | 0.19.3 | MIT License | https://github.com/tobgu/pyrsistent/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pytest | 7.2.0 | MIT License | https://docs.pytest.org/en/latest/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pytest-cov | 4.0.0 | MIT License | https://github.com/pytest-dev/pytest-cov |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pytest-flake8 | 1.1.1 | BSD License | https://github.com/tholo/pytest-flake8 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| python-dateutil | 2.8.2 | Apache Software License; BSD License | https://github.com/dateutil/dateutil |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| python-json-logger | 2.0.7 | BSD License | http://github.com/madzak/python-json-logger |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pytz | 2023.3 | MIT License | http://pythonhosted.org/pytz |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pywin32 | 306 | Python Software Foundation License | https://github.com/mhammond/pywin32 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pywinpty | 2.0.10 | MIT | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| pyzmq | 25.1.0 | BSD License; GNU Library or Lesser General Public License (LGPL) | https://pyzmq.readthedocs.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ray | 2.2.0 | Apache 2.0 | https://github.com/ray-project/ray |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| requests | 2.31.0 | Apache Software License | https://requests.readthedocs.io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| requests-oauthlib | 1.3.1 | BSD License | https://github.com/requests/requests-oauthlib |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| rfc3339-validator | 0.1.4 | MIT License | https://github.com/naimetti/rfc3339-validator |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| rfc3986-validator | 0.1.1 | MIT License | https://github.com/naimetti/rfc3986-validator |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| rich | 13.3.5 | MIT License | https://github.com/Textualize/rich |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| rsa | 4.9 | Apache Software License | https://stuvel.eu/rsa |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ruff | 0.0.272 | MIT License | https://github.com/charliermarsh/ruff |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| scikit-image | 0.20.0 | BSD License | https://scikit-image.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| scipy | 1.10.1 | BSD License | https://scipy.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| shellingham | 1.5.0.post1 | ISC License (ISCL) | https://github.com/sarugaku/shellingham |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| six | 1.16.0 | MIT License | https://github.com/benjaminp/six |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sniffio | 1.3.0 | Apache Software License; MIT License | https://github.com/python-trio/sniffio |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| snowballstemmer | 2.2.0 | BSD License | https://github.com/snowballstem/snowball |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| soupsieve | 2.4.1 | MIT License | https://github.com/facelessuser/soupsieve |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinx-basic-ng | 1.0.0b1 | MIT License | https://github.com/pradyunsg/sphinx-basic-ng |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinx-code-tabs | 0.5.3 | The Unlicense (Unlicense) | https://github.com/coldfix/sphinx-code-tabs |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinx-copybutton | 0.5.2 | MIT License | https://github.com/executablebooks/sphinx-copybutton |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinxcontrib-applehelp | 1.0.4 | BSD License | https://www.sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinxcontrib-devhelp | 1.0.2 | BSD License | http://sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinxcontrib-htmlhelp | 2.0.1 | BSD License | https://www.sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinxcontrib-jsmath | 1.0.1 | BSD License | http://sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinxcontrib-qthelp | 1.0.3 | BSD License | http://sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sphinxcontrib-serializinghtml | 1.1.5 | BSD License | http://sphinx-doc.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| stable-baselines3 | 1.6.2 | MIT | https://github.com/DLR-RM/stable-baselines3 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| stack-data | 0.6.2 | MIT License | http://github.com/alexmojaki/stack_data |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| sympy | 1.12 | BSD License | https://sympy.org |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tabulate | 0.9.0 | MIT License | https://github.com/astanin/python-tabulate |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tenacity | 8.2.2 | Apache Software License | https://github.com/jd/tenacity |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorboard | 2.11.2 | Apache Software License | https://github.com/tensorflow/tensorboard |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorboard-data-server | 0.6.1 | Apache Software License | https://github.com/tensorflow/tensorboard/tree/master/tensorboard/data/server |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorboard-plugin-wit | 1.8.1 | Apache 2.0 | https://whatif-tool.dev |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorboardX | 2.6 | MIT License | https://github.com/lanpa/tensorboardX |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorflow | 2.12.0 | Apache Software License | https://www.tensorflow.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorflow-estimator | 2.12.0 | Apache Software License | https://www.tensorflow.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorflow-intel | 2.12.0 | Apache Software License | https://www.tensorflow.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tensorflow-io-gcs-filesystem | 0.31.0 | Apache Software License | https://github.com/tensorflow/io |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| termcolor | 2.3.0 | MIT License | https://github.com/termcolor/termcolor |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| terminado | 0.17.1 | BSD License | https://github.com/jupyter/terminado |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tifffile | 2023.4.12 | BSD License | https://www.cgohlke.com |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tinycss2 | 1.2.1 | BSD License | https://www.courtbouillon.org/tinycss2 |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| toml | 0.10.2 | MIT License | https://github.com/uiri/toml |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tomli | 2.0.1 | MIT License | https://github.com/hukkin/tomli |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| torch | 2.0.1 | BSD License | https://pytorch.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tornado | 6.3.2 | Apache Software License | http://www.tornadoweb.org/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| traitlets | 5.9.0 | BSD License | https://github.com/ipython/traitlets |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| typer | 0.9.0 | MIT License | https://github.com/tiangolo/typer |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| typing_extensions | 4.6.2 | Python Software Foundation License | https://github.com/python/typing_extensions/issues |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| tzdata | 2023.3 | Apache Software License | https://github.com/python/tzdata |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| uri-template | 1.2.0 | MIT License | https://github.com/plinss/uri_template/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| urllib3 | 1.26.16 | MIT License | https://urllib3.readthedocs.io/ |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| virtualenv | 20.21.0 | MIT License | https://github.com/pypa/virtualenv |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| webcolors | 1.13 | BSD License | UNKNOWN |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| webencodings | 0.5.1 | BSD License | https://github.com/SimonSapin/python-webencodings |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| websocket-client | 1.5.2 | Apache Software License | https://github.com/websocket-client/websocket-client.git |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| wrapt | 1.14.1 | BSD License | https://github.com/GrahamDumpleton/wrapt |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| y-py | 0.5.9 | MIT License | https://github.com/y-crdt/ypy |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| ypy-websocket | 0.8.2 | UNKNOWN | https://github.com/y-crdt/ypy-websocket |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| zipp | 3.15.0 | MIT License | https://github.com/jaraco/zipp |
+-------------------------------+-------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+

1
src/primaite/acl/__init__.py
View File

@@ -1 +1,2 @@
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
"""Access Control List. Models firewall functionality."""

2
src/primaite/acl/access_control_list.py
View File

@@ -9,7 +9,7 @@ class AccessControlList:
"""Access Control List class.""" """Access Control List class."""
def __init__(self): def __init__(self):
"""Init.""" """Initialise an empty AccessControlList."""
self.acl: Dict[str, ACLRule] = {} # A dictionary of ACL Rules self.acl: Dict[str, ACLRule] = {} # A dictionary of ACL Rules
def check_address_match(self, _rule: ACLRule, _source_ip_address: str, _dest_ip_address: str) -> bool: def check_address_match(self, _rule: ACLRule, _source_ip_address: str, _dest_ip_address: str) -> bool:

13
src/primaite/acl/acl_rule.py
View File

@@ -7,14 +7,13 @@ class ACLRule:
def __init__(self, _permission, _source_ip, _dest_ip, _protocol, _port): def __init__(self, _permission, _source_ip, _dest_ip, _protocol, _port):
""" """
Init. Initialise an ACL Rule.
Args: :param _permission: The permission (ALLOW or DENY)
_permission: The permission (ALLOW or DENY) :param _source_ip: The source IP address
_source_ip: The source IP address :param _dest_ip: The destination IP address
_dest_ip: The destination IP address :param _protocol: The rule protocol
_protocol: The rule protocol :param _port: The rule port
_port: The rule port
""" """
self.permission = _permission self.permission = _permission
self.source_ip = _source_ip self.source_ip = _source_ip

1
src/primaite/agents/__init__.py
View File

@@ -0,0 +1 @@
"""Common interface between RL agents from different libraries and PrimAITE."""

28
src/primaite/agents/agent.py
View File

@@ -42,12 +42,21 @@ class AgentSessionABC(ABC):
""" """
An ABC that manages training and/or evaluation of agents in PrimAITE. An ABC that manages training and/or evaluation of agents in PrimAITE.
This class cannot be directly instantiated and must be inherited from This class cannot be directly instantiated and must be inherited from with all implemented abstract methods
with all implemented abstract methods implemented. implemented.
""" """
@abstractmethod @abstractmethod
def __init__(self, training_config_path, lay_down_config_path): def __init__(self, training_config_path, lay_down_config_path):
"""
Initialise an agent session from config files.
:param training_config_path: YAML file containing configurable items defined in
`primaite.config.training_config.TrainingConfig`
:type training_config_path: Union[path, str]
:param lay_down_config_path: YAML file containing configurable items for generating network laydown.
:type lay_down_config_path: Union[path, str]
"""
if not isinstance(training_config_path, Path): if not isinstance(training_config_path, Path):
training_config_path = Path(training_config_path) training_config_path = Path(training_config_path)
self._training_config_path: Final[Union[Path, str]] = training_config_path self._training_config_path: Final[Union[Path, str]] = training_config_path
@@ -55,7 +64,7 @@ class AgentSessionABC(ABC):
if not isinstance(lay_down_config_path, Path): if not isinstance(lay_down_config_path, Path):
lay_down_config_path = Path(lay_down_config_path) lay_down_config_path = Path(lay_down_config_path)
self._lay_down_config_path: Final[Union[Path]] = lay_down_config_path self._lay_down_config_path: Final[Union[Path, str]] = lay_down_config_path
self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path) self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path)
self.sb3_output_verbose_level = self._training_config.sb3_output_verbose_level self.sb3_output_verbose_level = self._training_config.sb3_output_verbose_level
@@ -305,11 +314,20 @@ class HardCodedAgentSessionABC(AgentSessionABC):
""" """
An Agent Session ABC for evaluation deterministic agents. An Agent Session ABC for evaluation deterministic agents.
This class cannot be directly instantiated and must be inherited from This class cannot be directly instantiated and must be inherited from with all implemented abstract methods
with all implemented abstract methods implemented. implemented.
""" """
def __init__(self, training_config_path, lay_down_config_path): def __init__(self, training_config_path, lay_down_config_path):
"""
Initialise a hardcoded agent session.
:param training_config_path: YAML file containing configurable items defined in
`primaite.config.training_config.TrainingConfig`
:type training_config_path: Union[path, str]
:param lay_down_config_path: YAML file containing configurable items for generating network laydown.
:type lay_down_config_path: Union[path, str]
"""
super().__init__(training_config_path, lay_down_config_path) super().__init__(training_config_path, lay_down_config_path)
self._setup() self._setup()

3
src/primaite/agents/hardcoded_acl.py
View File

@@ -439,7 +439,8 @@ class HardCodedACLAgent(HardCodedAgentSessionABC):
return action return action
def _calculate_action_basic_view(self, obs: np.ndarray) -> int: def _calculate_action_basic_view(self, obs: np.ndarray) -> int:
"""Calculate a good acl-based action for the blue agent to take. """
Calculate a good acl-based action for the blue agent to take.
Uses ONLY information from the current observation with NO knowledge Uses ONLY information from the current observation with NO knowledge
of previous actions taken and NO reward feedback. of previous actions taken and NO reward feedback.

12
src/primaite/agents/rllib.py
View File

@@ -44,6 +44,18 @@ class RLlibAgent(AgentSessionABC):
"""An AgentSession class that implements a Ray RLlib agent.""" """An AgentSession class that implements a Ray RLlib agent."""
def __init__(self, training_config_path, lay_down_config_path): def __init__(self, training_config_path, lay_down_config_path):
"""
Initialise the RLLib Agent training session.
:param training_config_path: YAML file containing configurable items defined in
`primaite.config.training_config.TrainingConfig`
:type training_config_path: Union[path, str]
:param lay_down_config_path: YAML file containing configurable items for generating network laydown.
:type lay_down_config_path: Union[path, str]
:raises ValueError: If the training config contains an unexpected value for agent_framework (should be "RLLIB")
:raises ValueError: If the training config contains an unexpected value for agent_identifies (should be `PPO`
or `A2C`)
"""
super().__init__(training_config_path, lay_down_config_path) super().__init__(training_config_path, lay_down_config_path)
if not self._training_config.agent_framework == AgentFramework.RLLIB: if not self._training_config.agent_framework == AgentFramework.RLLIB:
msg = f"Expected RLLIB agent_framework, " f"got {self._training_config.agent_framework}" msg = f"Expected RLLIB agent_framework, " f"got {self._training_config.agent_framework}"

12
src/primaite/agents/sb3.py
View File

@@ -19,6 +19,18 @@ class SB3Agent(AgentSessionABC):
"""An AgentSession class that implements a Stable Baselines3 agent.""" """An AgentSession class that implements a Stable Baselines3 agent."""
def __init__(self, training_config_path, lay_down_config_path): def __init__(self, training_config_path, lay_down_config_path):
"""
Initialise the SB3 Agent training session.
:param training_config_path: YAML file containing configurable items defined in
`primaite.config.training_config.TrainingConfig`
:type training_config_path: Union[path, str]
:param lay_down_config_path: YAML file containing configurable items for generating network laydown.
:type lay_down_config_path: Union[path, str]
:raises ValueError: If the training config contains an unexpected value for agent_framework (should be "SB3")
:raises ValueError: If the training config contains an unexpected value for agent_identifies (should be `PPO`
or `A2C`)
"""
super().__init__(training_config_path, lay_down_config_path) super().__init__(training_config_path, lay_down_config_path)
if not self._training_config.agent_framework == AgentFramework.SB3: if not self._training_config.agent_framework == AgentFramework.SB3:
msg = f"Expected SB3 agent_framework, " f"got {self._training_config.agent_framework}" msg = f"Expected SB3 agent_framework, " f"got {self._training_config.agent_framework}"

3
src/primaite/agents/simple.py
View File

@@ -17,8 +17,7 @@ class DummyAgent(HardCodedAgentSessionABC):
""" """
A Dummy Agent. A Dummy Agent.
All action spaces setup so dummy action is always 0 regardless of action All action spaces setup so dummy action is always 0 regardless of action type used.
type used.
""" """
def _calculate_action(self, obs): def _calculate_action(self, obs):

3
src/primaite/agents/utils.py
View File

@@ -67,7 +67,8 @@ def transform_action_acl_readable(action: List[str]) -> List[Union[str, int]]:
def is_valid_node_action(action: List[int]) -> bool: def is_valid_node_action(action: List[int]) -> bool:
"""Is the node action an actual valid action. """
Is the node action an actual valid action.
Only uses information about the action to determine if the action has an effect Only uses information about the action to determine if the action has an effect

1
src/primaite/common/__init__.py
View File

@@ -1 +1,2 @@
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
"""Objects which are shared between many PrimAITE modules."""

6
src/primaite/common/protocol.py
View File

@@ -7,10 +7,10 @@ class Protocol(object):
def __init__(self, _name): def __init__(self, _name):
""" """
Init. Initialise a protocol.
Args: :param _name: The name of the protocol
_name: The protocol name :type _name: str
""" """
self.name = _name self.name = _name
self.load = 0 # bps self.load = 0 # bps

2
src/primaite/common/service.py
View File

@@ -9,7 +9,7 @@ class Service(object):
def __init__(self, name: str, port: str, software_state: SoftwareState): def __init__(self, name: str, port: str, software_state: SoftwareState):
""" """
Init. Initialise a service.
:param name: The service name. :param name: The service name.
:param port: The service port. :param port: The service port.

1
src/primaite/config/__init__.py
View File

@@ -0,0 +1 @@
"""Configuration parameters for running experiments."""

3
src/primaite/config/lay_down_config.py
View File

@@ -26,8 +26,7 @@ def load(file_path: Union[str, Path], legacy_file: bool = False) -> Dict:
Read in a lay down config yaml file. Read in a lay down config yaml file.
:param file_path: The config file path. :param file_path: The config file path.
:param legacy_file: True if the config file is legacy format, otherwise :param legacy_file: True if the config file is legacy format, otherwise False.
False.
:return: The lay down config as a dict. :return: The lay down config as a dict.
:raises ValueError: If the file_path does not exist. :raises ValueError: If the file_path does not exist.
""" """

13
src/primaite/config/training_config.py
View File

@@ -291,14 +291,11 @@ def convert_legacy_training_config_dict(
Convert a legacy training config dict to the new format. Convert a legacy training config dict to the new format.
:param legacy_config_dict: A legacy training config dict. :param legacy_config_dict: A legacy training config dict.
:param agent_framework: The agent framework to use as legacy training :param agent_framework: The agent framework to use as legacy training configs don't have agent_framework values.
configs don't have agent_framework values. :param agent_identifier: The red agent identifier to use as legacy training configs don't have agent_identifier
:param agent_identifier: The red agent identifier to use as legacy values.
training configs don't have agent_identifier values. :param action_type: The action space type to set as legacy training configs don't have action_type values.
:param action_type: The action space type to set as legacy training configs :param num_steps: The number of steps to set as legacy training configs don't have num_steps values.
don't have action_type values.
:param num_steps: The number of steps to set as legacy training configs
don't have num_steps values.
:return: The converted training config dict. :return: The converted training config dict.
""" """
config_dict = { config_dict = {

1
src/primaite/data_viz/__init__.py
View File

@@ -1,3 +1,4 @@
"""Utility to generate plots of sessions metrics after PrimAITE."""
from enum import Enum from enum import Enum

1
src/primaite/environment/__init__.py
View File

@@ -1 +1,2 @@
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
"""Gym/Gymnasium environment for RL agents consisting of a simulated computer network."""

97
src/primaite/environment/observations.py
View File

@@ -25,6 +25,12 @@ class AbstractObservationComponent(ABC):
@abstractmethod @abstractmethod
def __init__(self, env: "Primaite"): def __init__(self, env: "Primaite"):
"""
Initialise observation component.
:param env: Primaite training environment.
:type env: Primaite
"""
_LOGGER.info(f"Initialising {self} observation component") _LOGGER.info(f"Initialising {self} observation component")
self.env: "Primaite" = env self.env: "Primaite" = env
self.space: spaces.Space self.space: spaces.Space
@@ -44,11 +50,13 @@ class AbstractObservationComponent(ABC):
class NodeLinkTable(AbstractObservationComponent): class NodeLinkTable(AbstractObservationComponent):
"""Table with nodes and links as rows and hardware/software status as cols. """
Table with nodes and links as rows and hardware/software status as cols.
This will create the observation space formatted as a table of integers. This will create the observation space formatted as a table of integers.
There is one row per node, followed by one row per link. There is one row per node, followed by one row per link.
The number of columns is 4 plus one per service. They are: The number of columns is 4 plus one per service. They are:
* node/link ID * node/link ID
* node hardware status / 0 for links * node hardware status / 0 for links
* node operating system status (if active/service) / 0 for links * node operating system status (if active/service) / 0 for links
@@ -67,6 +75,12 @@ class NodeLinkTable(AbstractObservationComponent):
_DATA_TYPE: type = np.int64 _DATA_TYPE: type = np.int64
def __init__(self, env: "Primaite"): def __init__(self, env: "Primaite"):
"""
Initialise a NodeLinkTable observation space component.
:param env: Training environment.
:type env: Primaite
"""
super().__init__(env) super().__init__(env)
# 1. Define the shape of your observation space component # 1. Define the shape of your observation space component
@@ -88,7 +102,8 @@ class NodeLinkTable(AbstractObservationComponent):
self.structure = self.generate_structure() self.structure = self.generate_structure()
def update(self): def update(self):
"""Update the observation based on current environment state. """
Update the observation based on current environment state.
The structure of the observation space is described in :class:`.NodeLinkTable` The structure of the observation space is described in :class:`.NodeLinkTable`
""" """
@@ -169,12 +184,14 @@ class NodeLinkTable(AbstractObservationComponent):
class NodeStatuses(AbstractObservationComponent): class NodeStatuses(AbstractObservationComponent):
"""Flat list of nodes' hardware, OS, file system, and service states. """
Flat list of nodes' hardware, OS, file system, and service states.
The MultiDiscrete observation space can be though of as a one-dimensional vector of discrete states, represented by The MultiDiscrete observation space can be though of as a one-dimensional vector of discrete states, represented by
integers. integers.
Each node has 3 elements plus 1 per service. It will have the following structure: Each node has 3 elements plus 1 per service. It will have the following structure:
.. code-block:: .. code-block::
[ [
node1 hardware state, node1 hardware state,
node1 OS state, node1 OS state,
@@ -190,14 +207,17 @@ class NodeStatuses(AbstractObservationComponent):
node2 serviceN state (one for each service), node2 serviceN state (one for each service),
... ...
] ]
:param env: The environment that forms the basis of the observations
:type env: Primaite
""" """
_DATA_TYPE: type = np.int64 _DATA_TYPE: type = np.int64
def __init__(self, env: "Primaite"): def __init__(self, env: "Primaite"):
"""
Initialise a NodeStatuses observation component.
:param env: Training environment.
:type env: Primaite
"""
super().__init__(env) super().__init__(env)
# 1. Define the shape of your observation space component # 1. Define the shape of your observation space component
@@ -218,7 +238,8 @@ class NodeStatuses(AbstractObservationComponent):
self.structure = self.generate_structure() self.structure = self.generate_structure()
def update(self): def update(self):
"""Update the observation based on current environment state. """
Update the observation based on current environment state.
The structure of the observation space is described in :class:`.NodeStatuses` The structure of the observation space is described in :class:`.NodeStatuses`
""" """
@@ -271,28 +292,22 @@ class NodeStatuses(AbstractObservationComponent):
class LinkTrafficLevels(AbstractObservationComponent): class LinkTrafficLevels(AbstractObservationComponent):
"""Flat list of traffic levels encoded into banded categories. """
Flat list of traffic levels encoded into banded categories.
For each link, total traffic or traffic per service is encoded into a categorical value. For each link, total traffic or traffic per service is encoded into a categorical value.
For example, if ``quantisation_levels=5``, the traffic levels represent these values: For example, if ``quantisation_levels=5``, the traffic levels represent these values:
0 = No traffic (0% of bandwidth)
1 = No traffic (0%-33% of bandwidth) * 0 = No traffic (0% of bandwidth)
2 = No traffic (33%-66% of bandwidth) * 1 = No traffic (0%-33% of bandwidth)
3 = No traffic (66%-100% of bandwidth) * 2 = No traffic (33%-66% of bandwidth)
4 = No traffic (100% of bandwidth) * 3 = No traffic (66%-100% of bandwidth)
* 4 = No traffic (100% of bandwidth)
.. note:: .. note::
The lowest category always corresponds to no traffic and the highest category to the link being at max capacity. The lowest category always corresponds to no traffic and the highest category to the link being at max capacity.
Any amount of traffic between 0% and 100% (exclusive) is divided evenly into the remaining categories. Any amount of traffic between 0% and 100% (exclusive) is divided evenly into the remaining categories.
:param env: The environment that forms the basis of the observations
:type env: Primaite
:param combine_service_traffic: Whether to consider total traffic on the link, or each protocol individually,
defaults to False
:type combine_service_traffic: bool, optional
:param quantisation_levels: How many bands to consider when converting the traffic amount to a categorical value ,
defaults to 5
:type quantisation_levels: int, optional
""" """
_DATA_TYPE: type = np.int64 _DATA_TYPE: type = np.int64
@@ -303,6 +318,18 @@ class LinkTrafficLevels(AbstractObservationComponent):
combine_service_traffic: bool = False, combine_service_traffic: bool = False,
quantisation_levels: int = 5, quantisation_levels: int = 5,
): ):
"""
Initialise a LinkTrafficLevels observation component.
:param env: The environment that forms the basis of the observations
:type env: Primaite
:param combine_service_traffic: Whether to consider total traffic on the link, or each protocol individually,
defaults to False
:type combine_service_traffic: bool, optional
:param quantisation_levels: How many bands to consider when converting the traffic amount to a categorical
value, defaults to 5
:type quantisation_levels: int, optional
"""
if quantisation_levels < 3: if quantisation_levels < 3:
_msg = ( _msg = (
f"quantisation_levels must be 3 or more because the lowest and highest levels are " f"quantisation_levels must be 3 or more because the lowest and highest levels are "
@@ -333,7 +360,8 @@ class LinkTrafficLevels(AbstractObservationComponent):
self.structure = self.generate_structure() self.structure = self.generate_structure()
def update(self): def update(self):
"""Update the observation based on current environment state. """
Update the observation based on current environment state.
The structure of the observation space is described in :class:`.LinkTrafficLevels` The structure of the observation space is described in :class:`.LinkTrafficLevels`
""" """
@@ -374,10 +402,11 @@ class LinkTrafficLevels(AbstractObservationComponent):
class ObservationsHandler: class ObservationsHandler:
"""Component-based observation space handler. """
Component-based observation space handler.
This allows users to configure observation spaces by mixing and matching components. This allows users to configure observation spaces by mixing and matching components. Each component can also define
Each component can also define further parameters to make them more flexible. further parameters to make them more flexible.
""" """
_REGISTRY: Final[Dict[str, type]] = { _REGISTRY: Final[Dict[str, type]] = {
@@ -387,6 +416,7 @@ class ObservationsHandler:
} }
def __init__(self): def __init__(self):
"""Initialise the observation handler."""
self.registered_obs_components: List[AbstractObservationComponent] = [] self.registered_obs_components: List[AbstractObservationComponent] = []
# internal the observation space (unflattened version of space if flatten=True) # internal the observation space (unflattened version of space if flatten=True)
@@ -414,7 +444,8 @@ class ObservationsHandler:
self._flat_observation = spaces.flatten(self._space, self._observation) self._flat_observation = spaces.flatten(self._space, self._observation)
def register(self, obs_component: AbstractObservationComponent): def register(self, obs_component: AbstractObservationComponent):
"""Add a component for this handler to track. """
Add a component for this handler to track.
:param obs_component: The component to add. :param obs_component: The component to add.
:type obs_component: AbstractObservationComponent :type obs_component: AbstractObservationComponent
@@ -423,10 +454,11 @@ class ObservationsHandler:
self.update_space() self.update_space()
def deregister(self, obs_component: AbstractObservationComponent): def deregister(self, obs_component: AbstractObservationComponent):
"""Remove a component from this handler. """
Remove a component from this handler.
:param obs_component: Which component to remove. It must exist within this object's :param obs_component: Which component to remove. It must exist within this object's
``registered_obs_components`` attribute. ``registered_obs_components`` attribute.
:type obs_component: AbstractObservationComponent :type obs_component: AbstractObservationComponent
""" """
self.registered_obs_components.remove(obs_component) self.registered_obs_components.remove(obs_component)
@@ -466,11 +498,13 @@ class ObservationsHandler:
@classmethod @classmethod
def from_config(cls, env: "Primaite", obs_space_config: dict): def from_config(cls, env: "Primaite", obs_space_config: dict):
"""Parse a config dictinary, return a new observation handler populated with new observation component objects. """
Parse a config dictinary, return a new observation handler populated with new observation component objects.
The expected format for the config dictionary is: The expected format for the config dictionary is:
..code-block::python .. code-block:: python
config = { config = {
components: [ components: [
{ {
@@ -510,7 +544,8 @@ class ObservationsHandler:
return handler return handler
def describe_structure(self): def describe_structure(self):
"""Create a list of names for the features of the obs space. """
Create a list of names for the features of the obs space.
The order of labels follows the flattened version of the space. The order of labels follows the flattened version of the space.
""" """

19
src/primaite/environment/primaite_env.py
View File

@@ -73,8 +73,7 @@ class Primaite(Env):
:param training_config_path: The training config filepath. :param training_config_path: The training config filepath.
:param lay_down_config_path: The lay down config filepath. :param lay_down_config_path: The lay down config filepath.
:param session_path: The directory path the session is writing to. :param session_path: The directory path the session is writing to.
:param timestamp_str: The session timestamp in the format: :param timestamp_str: The session timestamp in the format: <yyyy-mm-dd>_<hh-mm- ss>.
<yyyy-mm-dd>_<hh-mm-ss>.
""" """
self.session_path: Final[Path] = session_path self.session_path: Final[Path] = session_path
self.timestamp_str: Final[str] = timestamp_str self.timestamp_str: Final[str] = timestamp_str
@@ -660,7 +659,8 @@ class Primaite(Env):
pass pass
def init_observations(self) -> Tuple[spaces.Space, np.ndarray]: def init_observations(self) -> Tuple[spaces.Space, np.ndarray]:
"""Create the environment's observation handler. """
Create the environment's observation handler.
:return: The observation space, initial observation (zeroed out array with the correct shape) :return: The observation space, initial observation (zeroed out array with the correct shape)
:rtype: Tuple[spaces.Space, np.ndarray] :rtype: Tuple[spaces.Space, np.ndarray]
@@ -1040,7 +1040,8 @@ class Primaite(Env):
self.num_ports = len(self.ports_list) self.num_ports = len(self.ports_list)
def get_observation_info(self, observation_info): def get_observation_info(self, observation_info):
"""Extracts observation_info. """
Extracts observation_info.
:param observation_info: Config item that defines which type of observation space to use :param observation_info: Config item that defines which type of observation space to use
:type observation_info: str :type observation_info: str
@@ -1057,7 +1058,8 @@ class Primaite(Env):
self.action_type = ActionType[action_info["type"]] self.action_type = ActionType[action_info["type"]]
def save_obs_config(self, obs_config: dict): def save_obs_config(self, obs_config: dict):
"""Cache the config for the observation space. """
Cache the config for the observation space.
This is necessary as the observation space can't be built while reading the config, This is necessary as the observation space can't be built while reading the config,
it must be done after all the nodes, links, and services have been initialised. it must be done after all the nodes, links, and services have been initialised.
@@ -1070,10 +1072,9 @@ class Primaite(Env):
def reset_environment(self): def reset_environment(self):
""" """
# Resets environment. Resets environment.
Uses config data config data in order to build the environment Uses config data config data in order to build the environment configuration.
configuration.
""" """
for item in self.lay_down_config: for item in self.lay_down_config:
if item["item_type"] == "NODE": if item["item_type"] == "NODE":
@@ -1157,7 +1158,6 @@ class Primaite(Env):
5: [1, 3, 1, 0], 5: [1, 3, 1, 0],
... ...
} }
""" """
# reserve 0 action to be a nothing action # reserve 0 action to be a nothing action
actions = {0: [1, 0, 0, 0]} actions = {0: [1, 0, 0, 0]}
@@ -1213,7 +1213,6 @@ class Primaite(Env):
Create a dictionary mapping each possible discrete action to a more readable mutlidiscrete action. Create a dictionary mapping each possible discrete action to a more readable mutlidiscrete action.
The dictionary contains actions of both Node and ACL action types. The dictionary contains actions of both Node and ACL action types.
""" """
node_action_dict = self.create_node_action_dict() node_action_dict = self.create_node_action_dict()
acl_action_dict = self.create_acl_action_dict() acl_action_dict = self.create_acl_action_dict()

1
src/primaite/links/__init__.py
View File

@@ -1 +1,2 @@
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
"""Network connections between nodes in the simulation."""

13
src/primaite/links/link.py
View File

@@ -10,14 +10,13 @@ class Link(object):
def __init__(self, _id, _bandwidth, _source_node_name, _dest_node_name, _services): def __init__(self, _id, _bandwidth, _source_node_name, _dest_node_name, _services):
""" """
Init. Initialise a Link within the simulated network.
Args: :param _id: The IER id
_id: The IER id :param _bandwidth: The bandwidth of the link (bps)
_bandwidth: The bandwidth of the link (bps) :param _source_node_name: The name of the source node
_source_node_name: The name of the source node :param _dest_node_name: The name of the destination node
_dest_node_name: The name of the destination node :param _protocols: The protocols to add to the link
_protocols: The protocols to add to the link
""" """
self.id = _id self.id = _id
self.bandwidth = _bandwidth self.bandwidth = _bandwidth

3
src/primaite/main.py
View File

@@ -14,7 +14,8 @@ def run(
training_config_path: Union[str, Path], training_config_path: Union[str, Path],
lay_down_config_path: Union[str, Path], lay_down_config_path: Union[str, Path],
): ):
"""Run the PrimAITE Session. """
Run the PrimAITE Session.
:param training_config_path: The training config filepath. :param training_config_path: The training config filepath.
:param lay_down_config_path: The lay down config filepath. :param lay_down_config_path: The lay down config filepath.

1
src/primaite/nodes/__init__.py
View File

@@ -1 +1,2 @@
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
"""Nodes represent network hosts in the simulation."""

2
src/primaite/nodes/active_node.py
View File

@@ -26,7 +26,7 @@ class ActiveNode(Node):
config_values: TrainingConfig, config_values: TrainingConfig,
): ):
""" """
Init. Initialise an active node.
:param node_id: The node ID :param node_id: The node ID
:param name: The node name :param name: The node name

2
src/primaite/nodes/node.py
View File

@@ -19,7 +19,7 @@ class Node:
config_values: TrainingConfig, config_values: TrainingConfig,
): ):
""" """
Init. Initialise a node.
:param node_id: The node id. :param node_id: The node id.
:param name: The name of the node. :param name: The name of the node.

17
src/primaite/nodes/node_state_instruction_green.py
View File

@@ -16,16 +16,15 @@ class NodeStateInstructionGreen(object):
_state, _state,
): ):
""" """
Init. Initialise the Node State Instruction.
Args: :param _id: The node state instruction id
_id: The node state instruction id :param _start_step: The start step of the instruction
_start_step: The start step of the instruction :param _end_step: The end step of the instruction
_end_step: The end step of the instruction :param _node_id: The id of the associated node
_node_id: The id of the associated node :param _node_pol_type: The pattern of life type
_node_pol_type: The pattern of life type :param _service_name: The service name
_service_name: The service name :param _state: The state (node or service)
_state: The state (node or service)
""" """
self.id = _id self.id = _id
self.start_step = _start_step self.start_step = _start_step

25
src/primaite/nodes/node_state_instruction_red.py
View File

@@ -24,20 +24,19 @@ class NodeStateInstructionRed(object):
_pol_source_node_service_state, _pol_source_node_service_state,
): ):
""" """
Init. Initialise the Node State Instruction for the red agent.
Args: :param _id: The node state instruction id
_id: The node state instruction id :param _start_step: The start step of the instruction
_start_step: The start step of the instruction :param _end_step: The end step of the instruction
_end_step: The end step of the instruction :param _target_node_id: The id of the associated node
_target_node_id: The id of the associated node :param -pol_initiator: The way the PoL is applied (DIRECT, IER or SERVICE)
-pol_initiator: The way the PoL is applied (DIRECT, IER or SERVICE) :param _pol_type: The pattern of life type
_pol_type: The pattern of life type :param pol_protocol: The pattern of life protocol/service affected
-pol_protocol: The pattern of life protocol/service affected :param _pol_state: The state (node or service)
_pol_state: The state (node or service) :param _pol_source_node_id: The source node Id (used for initiator type SERVICE)
_pol_source_node_id: The source node Id (used for initiator type SERVICE) :param _pol_source_node_service: The source node service (used for initiator type SERVICE)
_pol_source_node_service: The source node service (used for initiator type SERVICE) :param _pol_source_node_service_state: The source node service state (used for initiator type SERVICE)
_pol_source_node_service_state: The source node service state (used for initiator type SERVICE)
""" """
self.id = _id self.id = _id
self.start_step = _start_step self.start_step = _start_step

2
src/primaite/nodes/passive_node.py
View File

@@ -18,7 +18,7 @@ class PassiveNode(Node):
config_values: TrainingConfig, config_values: TrainingConfig,
): ):
""" """
Init. Initialise a passive node.
:param node_id: The node id. :param node_id: The node id.
:param name: The name of the node. :param name: The name of the node.

8
src/primaite/nodes/service_node.py
View File

@@ -27,7 +27,7 @@ class ServiceNode(ActiveNode):
config_values: TrainingConfig, config_values: TrainingConfig,
): ):
""" """
Init. Initialise a Service Node.
:param node_id: The node ID :param node_id: The node ID
:param name: The node name :param name: The node name
@@ -77,8 +77,7 @@ class ServiceNode(ActiveNode):
Indicates whether a service is in a running state on the node. Indicates whether a service is in a running state on the node.
:param protocol_name: The service (protocol) :param protocol_name: The service (protocol)
:return: True if service (protocol) is in a running state on the :return: True if service (protocol) is in a running state on the node, otherwise False.
node, otherwise False.
""" """
for service_key, service_value in self.services.items(): for service_key, service_value in self.services.items():
if service_key == protocol_name: if service_key == protocol_name:
@@ -93,8 +92,7 @@ class ServiceNode(ActiveNode):
Indicates whether a service is in an overwhelmed state on the node. Indicates whether a service is in an overwhelmed state on the node.
:param protocol_name: The service (protocol) :param protocol_name: The service (protocol)
:return: True if service (protocol) is in an overwhelmed state on the :return: True if service (protocol) is in an overwhelmed state on the node, otherwise False.
node, otherwise False.
""" """
for service_key, service_value in self.services.items(): for service_key, service_value in self.services.items():
if service_key == protocol_name: if service_key == protocol_name:

1
src/primaite/notebooks/__init__.py
View File

@@ -1,3 +1,4 @@
"""Contains default jupyter notebooks which demonstrate PrimAITE functionality."""
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
import importlib.util import importlib.util
import os import os

1
src/primaite/pol/__init__.py
View File

@@ -1 +1,2 @@
"""Pattern of Life- Represents the actions of users on the network."""
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

23
src/primaite/pol/ier.py
View File

@@ -23,19 +23,18 @@ class IER(object):
_running=False, _running=False,
): ):
""" """
Init. Initialise an Information Exchange Request.
Args: :param _id: The IER id
_id: The IER id :param _start_step: The step when this IER should start
_start_step: The step when this IER should start :param _end_step: The step when this IER should end
_end_step: The step when this IER should end :param _load: The load this IER should put on a link (bps)
_load: The load this IER should put on a link (bps) :param _protocol: The protocol of this IER
_protocol: The protocol of this IER :param _port: The port this IER runs on
_port: The port this IER runs on :param _source_node_id: The source node ID
_source_node_id: The source node ID :param _dest_node_id: The destination node ID
_dest_node_id: The destination node ID :param _mission_criticality: Criticality of this IER to the mission (0 none, 5 mission critical)
_mission_criticality: Criticality of this IER to the mission (0 none, 5 mission critical) :param _running: Indicates whether the IER is currently running
_running: Indicates whether the IER is currently running
""" """
self.id = _id self.id = _id
self.start_step = _start_step self.start_step = _start_step

8
src/primaite/primaite_session.py
View File

@@ -1,3 +1,4 @@
"""Main entry point to PrimAITE. Configure training/evaluation experiments and input/output."""
from __future__ import annotations from __future__ import annotations
from pathlib import Path from pathlib import Path
@@ -21,8 +22,7 @@ class PrimaiteSession:
""" """
The PrimaiteSession class. The PrimaiteSession class.
Provides a single learning and evaluation entry point for all training Provides a single learning and evaluation entry point for all training and lay down configurations.
and lay down configurations.
""" """
def __init__( def __init__(
@@ -38,12 +38,12 @@ class PrimaiteSession:
""" """
if not isinstance(training_config_path, Path): if not isinstance(training_config_path, Path):
training_config_path = Path(training_config_path) training_config_path = Path(training_config_path)
self._training_config_path: Final[Union[Path]] = training_config_path self._training_config_path: Final[Union[Path, str]] = training_config_path
self._training_config: Final[TrainingConfig] = training_config.load(self._training_config_path) self._training_config: Final[TrainingConfig] = training_config.load(self._training_config_path)
if not isinstance(lay_down_config_path, Path): if not isinstance(lay_down_config_path, Path):
lay_down_config_path = Path(lay_down_config_path) lay_down_config_path = Path(lay_down_config_path)
self._lay_down_config_path: Final[Union[Path]] = lay_down_config_path self._lay_down_config_path: Final[Union[Path, str]] = lay_down_config_path
self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path) self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path)
self._agent_session: AgentSessionABC = None # noqa self._agent_session: AgentSessionABC = None # noqa

1
src/primaite/setup/__init__.py
View File

@@ -1 +1,2 @@
"""Utilities to prepare the user's data folders."""
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

3
src/primaite/setup/reset_demo_notebooks.py
View File

@@ -15,8 +15,7 @@ def run(overwrite_existing: bool = True):
""" """
Resets the demo jupyter notebooks in the users app notebooks directory. Resets the demo jupyter notebooks in the users app notebooks directory.
:param overwrite_existing: A bool to toggle replacing existing edited :param overwrite_existing: A bool to toggle replacing existing edited notebooks on or off.
notebooks on or off.
""" """
notebooks_package_data_root = pkg_resources.resource_filename("primaite", "notebooks/_package_data") notebooks_package_data_root = pkg_resources.resource_filename("primaite", "notebooks/_package_data")
for subdir, dirs, files in os.walk(notebooks_package_data_root): for subdir, dirs, files in os.walk(notebooks_package_data_root):

3
src/primaite/setup/reset_example_configs.py
View File

@@ -14,8 +14,7 @@ def run(overwrite_existing=True):
""" """
Resets the example config files in the users app config directory. Resets the example config files in the users app config directory.
:param overwrite_existing: A bool to toggle replacing existing edited :param overwrite_existing: A bool to toggle replacing existing edited config on or off.
config on or off.
""" """
configs_package_data_root = pkg_resources.resource_filename("primaite", "config/_package_data") configs_package_data_root = pkg_resources.resource_filename("primaite", "config/_package_data")

1
src/primaite/transactions/__init__.py
View File

@@ -1 +1,2 @@
"""Record data of the system's state and agent's observations and actions."""
# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence. # Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

3
src/primaite/transactions/transaction.py
View File

@@ -86,8 +86,7 @@ def _turn_obs_space_to_array(obs_space, obs_assets, obs_features) -> List[str]:
Turns observation space into a string array so it can be saved to csv. Turns observation space into a string array so it can be saved to csv.
:param obs_space: The observation space :param obs_space: The observation space
:param obs_assets: The number of assets (i.e. nodes or links) in the :param obs_assets: The number of assets (i.e. nodes or links) in the observation space
observation space
:param obs_features: The number of features associated with the asset :param obs_features: The number of features associated with the asset
:return: The observation space as an array of strings :return: The observation space as an array of strings
""" """

1
src/primaite/utils/__init__.py
View File

@@ -0,0 +1 @@
"""Utilities for PrimAITE."""

3
src/primaite/utils/session_output_reader.py
View File

@@ -10,8 +10,7 @@ def av_rewards_dict(av_rewards_csv_file: Union[str, Path]) -> Dict[int, float]:
""" """
Read an average rewards per episode csv file and return as a dict. Read an average rewards per episode csv file and return as a dict.
The dictionary keys are the episode number, and the values are the mean The dictionary keys are the episode number, and the values are the mean reward that episode.
reward that episode.
:param av_rewards_csv_file: The average rewards per episode csv file path. :param av_rewards_csv_file: The average rewards per episode csv file path.
:return: The average rewards per episode cdv as a dict. :return: The average rewards per episode cdv as a dict.

15
src/primaite/utils/session_output_writer.py
View File

@@ -29,6 +29,18 @@ class SessionOutputWriter:
transaction_writer: bool = False, transaction_writer: bool = False,
learning_session: bool = True, learning_session: bool = True,
): ):
"""
Initialise the Session Output Writer.
:param env: PrimAITE gym environment.
:type env: Primaite
:param transaction_writer: If `true`, this will output a full account of every transaction taken by the agent.
If `false` it will output the average reward per episode, defaults to False
:type transaction_writer: bool, optional
:param learning_session: Set to `true` to indicate that the current session is a training session. This
determines the name of the folder which contains the final output csv. Defaults to True
:type learning_session: bool, optional
"""
self._env = env self._env = env
self.transaction_writer = transaction_writer self.transaction_writer = transaction_writer
self.learning_session = learning_session self.learning_session = learning_session
@@ -68,8 +80,7 @@ class SessionOutputWriter:
""" """
Write a row of session data. Write a row of session data.
:param data: The row of data to write. Can be a Tuple or an instance :param data: The row of data to write. Can be a Tuple or an instance of Transaction.
of Transaction.
""" """
if isinstance(data, Transaction): if isinstance(data, Transaction):
header, data = data.as_csv_data() header, data = data.as_csv_data()

9
tests/test_observation_space.py
View File

@@ -75,7 +75,8 @@ class TestNodeLinkTable:
assert env.env_obs.shape == (5, 6) assert env.env_obs.shape == (5, 6)
def test_value(self, temp_primaite_session): def test_value(self, temp_primaite_session):
"""Test that the observation is generated correctly. """
Test that the observation is generated correctly.
The laydown has: The laydown has:
* 3 nodes (2 service nodes and 1 active node) * 3 nodes (2 service nodes and 1 active node)
@@ -157,7 +158,8 @@ class TestNodeStatuses:
assert env.env_obs.shape == (15,) assert env.env_obs.shape == (15,)
def test_values(self, temp_primaite_session): def test_values(self, temp_primaite_session):
"""Test that the hardware and software states are encoded correctly. """
Test that the hardware and software states are encoded correctly.
The laydown has: The laydown has:
* one node with a compromised operating system state * one node with a compromised operating system state
@@ -213,7 +215,8 @@ class TestLinkTrafficLevels:
assert env.env_obs.shape == (2 * 2,) assert env.env_obs.shape == (2 * 2,)
def test_values(self, temp_primaite_session): def test_values(self, temp_primaite_session):
"""Test that traffic values are encoded correctly. """
Test that traffic values are encoded correctly.
The laydown has: The laydown has:
* two services * two services