Merged PR 144: v2.0.0 GitHub release sync

v2.0.0 GitHub release sync

Related work items: #901, #1523, #1574, #1594, #1595, #1597, #1623, #1626, #1629, #1631, #1632, #1635, #1637, #1638, #1639, #1640, #1641, #1647, #1648, #1650

.azuredevops/pull_request_template.md

@@ -1,12 +1,12 @@
-## Summary
-*Replace this text with an explanation of what the changes are and how you implemented them. Can this impact any other parts of the codebase that we should keep in mind?*
-
-## Test process
-*How have you tested this (if applicable)?*
-
-## Checklist
-- [ ] This PR is linked to a **work item**
-- [ ] I have performed **self-review** of the code
-- [ ] I have written **tests** for any new functionality added with this PR
-- [ ] I have updated the **documentation** if this PR changes or adds functionality
-- [ ] I have run **pre-commit** checks for code style
+## Summary
+*Replace this text with an explanation of what the changes are and how you implemented them. Can this impact any other parts of the codebase that we should keep in mind?*
+
+## Test process
+*How have you tested this (if applicable)?*
+
+## Checklist
+- [ ] This PR is linked to a **work item**
+- [ ] I have performed **self-review** of the code
+- [ ] I have written **tests** for any new functionality added with this PR
+- [ ] I have updated the **documentation** if this PR changes or adds functionality
+- [ ] I have run **pre-commit** checks for code style

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] - <bug title goes here>"
+labels: bug
+assignees: ''
+
+---
+
+### Describe the bug:
+
+A clear and concise description of what the bug is.
+
+### To Reproduce:
+
+Steps to reproduce the behaviour:
+
+1. Import '...'
+2. Instantiate '....'
+3. Pass to '....'
+4. Run '....'
+5. See error
+
+### Expected behaviour
+
+A clear and concise description of what you expected to happen.
+
+### Screenshots/Outputs
+
+If applicable, add screenshots to help explain your problem.
+
+### Environment (please complete the following information)
+
+ - **OS:** [e.g. Ubuntu 22.04]
+ - **Python:** [e.g. 3.10.11]
+ - **PrimAITE Version:** [e.g. v2.0.0]
+ - **Software:** [e.g. cli, Jupyter, PyCharm, VSCode etc.]
+
+### Additional context
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[REQUEST] - <request title goes here>"
+labels: feature_request
+assignees: ''
+
+---
+
+### Is your feature request related to a problem?
+
+If so, please give a concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+### Describe the solution you'd like:
+
+A clear and concise description of what you want to happen.
+
+### Describe alternatives you've considered:
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context:
+
+Add any other context or screenshots about the feature request here.

.github/workflows/python-package.yml

@@ -0,0 +1,66 @@
+name: Python package
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - dev-gui
+      - 'release/**'
+  pull_request:
+    branches:
+      - main
+      - dev
+      - dev-gui
+      - 'release/**'
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install python dev
+        run: |
+          sudo apt update
+          sudo add-apt-repository ppa:deadsnakes/ppa -y
+          sudo apt install python${{ matrix.python-version}}-dev -y
+
+      - name: Install Build Dependencies
+        run: |
+          python -m pip install --upgrade pip==23.0.1
+          pip install wheel==0.38.4 --upgrade
+          pip install setuptools==66 --upgrade
+          pip install build
+
+      - name: Build PrimAITE
+        run: |
+          python -m build
+
+      - name: Install PrimAITE
+        run: |
+          PRIMAITE_WHEEL=$(ls ./dist/primaite*.whl)
+          python -m pip install $PRIMAITE_WHEEL[dev]
+
+      - name: Perform PrimAITE Setup
+        run: |
+          primaite setup
+
+      - name: Lint with flake8
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings.
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
+
+      - name: Run tests
+        run: |
+          pytest tests/

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# How to contribute to PrimAITE?
+
+
+### **Did you find a bug?**
+
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues).
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D+-+%3Cbug+title+goes+here%3E). Be sure to follow our bug report template with the headers **Describe the bug**, **To Reproduce**, **Expected behaviour**, **Screenshots/Outputs**, **Environment**, and **Additional context**
+
+
+### **Do you have a solution to fix the bug?**
+
+* [Fork the repository](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/fork).
+* Install the pre-commit hook with `pre-commit install`.
+* Implement the bug fix.
+* Update documentation where applicable.
+* Update the **UNRELEASED** section of the [CHANGELOG.md](CHANGELOG.md) file
+* Write a suitable test/tests.
+* Commit the bug fix to the dev branch on your fork. If the bug has an open issue under [Issues](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues), reference the issue in the commit message (e.g. #1 references issue 1).
+* Submit a pull request from your dev branch to the Autonomous-Resilient-Cyber-Defence/PrimAITE dev branch. Again, if the bug has an open issue under [Issues](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues), reference the issue in the pull request description.
+
+### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
+
+Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of PrimAITE will generally not be accepted.
+
+### **Do you intend to add a new feature or change an existing one?**
+
+* Submit a [feature request issue](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues/new?assignees=&labels=feature_request&projects=&template=feature_request.md&title=%5BREQUEST%5D+-+%3Crequest+title+goes+here%3E).
+* Know how to implement the new feature or change? Follow the same steps in the bug fix section above to fork, build, document, test, commit, and submit a pull request.
+
+### **Do you have questions about the source code?**
+
+Ask any question about how to use PrimAITE in our discussions section.
+
+### **Do you want to contribute to the PrimAITE documentation?**
+
+Please follow the "Do you intend to add a new feature or change an existing one?" section above and tag your feature request issue and pull request with the documentation tag.
+
+Thank you from the PrimAITE dev team! 🙌

README.md

@@ -1,50 +1,108 @@
 # PrimAITE
 
+PrimAITE (Primary-level AI Training Environment) is a simulation environment for training AI under the ARCD programme.
+
 ## Getting Started with PrimAITE
 
-### Pre-Requisites
-
-In order to get **PrimAITE** installed, you will need to have the following installed:
-
-- `python3.8+`
-- `python3-pip`
-- `virtualenv`
-
+### 💫 Install & Run
 **PrimAITE** is designed to be OS-agnostic, and thus should work on most variations/distros of Linux, Windows, and MacOS.
+Currently, the PRimAITE wheel can only be installed from GitHub. This may change in the future with release to PyPi.
 
-### Installation from source
-#### 1. Navigate to the PrimAITE folder and create a new python virtual environment (venv)
+#### Windows (PowerShell)
 
-```unix
-python3 -m venv <name_of_venv>
+**Prerequisites:**
+* Manual install of Python >= 3.8 < 3.11
+
+**Install:**
+
+``` powershell
+mkdir ~\primaite
+cd ~\primaite
+python3 -m venv .venv
+attrib +h .venv /s /d # Hides the .venv directory
+.\.venv\Scripts\activate
+pip install https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/download/v2.0.0/primaite-2.0.0-py3-none-any.whl
+primaite setup
 ```
 
-#### 2. Activate the venv
+**Run:**
+
+``` bash
+primaite session
+```
+
+#### Unix
+
+**Prerequisites:**
+* Manual install of Python >= 3.8 < 3.11
+
+``` bash
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt install python3.10
+sudo apt-get install python3-pip
+sudo apt-get install python3-venv
+```
+**Install:**
+
+``` bash
+mkdir ~/primaite
+cd ~/primaite
+python3 -m venv .venv
+source .venv/bin/activate
+pip install https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/download/v2.0.0/primaite-2.0.0-py3-none-any.whl
+primaite setup
+```
+
+**Run:**
+
+``` bash
+primaite session
+```
+
+
+### Developer Install from Source
+To make your own changes to PrimAITE, perform the install from source (developer install)
+
+#### 1. Clone the PrimAITE repository
+``` unix
+git clone git@github.com:Autonomous-Resilient-Cyber-Defence/PrimAITE.git
+```
+
+#### 2. CD into the repo directory
+``` unix
+cd PrimAITE
+```
+#### 3. Create a new python virtual environment (venv)
+
+```unix
+python3 -m venv venv
+```
+
+#### 4. Activate the venv
 
 ##### Unix
 ```bash
-source <name_of_venv>/bin/activate
+source venv/bin/activate
 ```
 
-##### Windows
+##### Windows (Powershell)
 ```powershell
-.\<name_of_venv>\Scripts\activate
+.\venv\Scripts\activate
 ```
 
-#### 3. Install `primaite` into the venv along with all of it's dependencies
-
-```bash
-python3 -m pip install -e .
-```
-
-### Development Installation
-To install the development dependencies, postfix the command in step 3 above with the `[dev]` extra. Example:
+#### 5. Install `primaite` with the dev extra into the venv along with all of it's dependencies
 
 ```bash
 python3 -m pip install -e .[dev]
 ```
 
-## Building documentation
+#### 6. Perform the PrimAITE setup:
+
+```bash
+primaite setup
+```
+
+## 📚 Building documentation
 The PrimAITE documentation can be built with the following commands:
 
 ##### Unix
@@ -53,12 +111,8 @@ cd docs
 make html
 ```
 
-##### Windows
+##### Windows (Powershell)
 ```powershell
 cd docs
 .\make.bat html
 ```
-
-This will build the documentation as a collection of HTML files which uses the Read The Docs sphinx theme. Other build
-options are available but may require additional dependencies such as LaTeX and PDF. Please refer to the Sphinx documentation
-for your specific output requirements.

docs/index.rst

@@ -14,9 +14,7 @@ PrimAITE (Primary-level AI Training Environment) is a simulation environment for
 * The ability to model key characteristics of a platform / system by representing connections, IP addresses, ports, traffic loading, operating systems, file system, services and processes;
 * Operates at machine-speed to enable fast training cycles.
 
-PrimAITE aims to evolve into an ARCD environment that could be used as the follow-on from Reception level approaches (e.g. YAWNING TITAN), and help bridge the Sim-to-Real gap into Secondary level environments (e.g. IMAGINARY YAK).
-
-This is similar to the approach taken by FVEY international partners (e.g. AUS CyBORG, US NSA FARLAND and CAN CyGil). These environments are referenced by the Dstl ARCD Agent Training Environments Knowledge Transfer document (TR141342).
+PrimAITE aims to evolve into an ARCD environment that could be used as the follow-on from Reception level approaches (e.g. `Yawning-Titan <https://github.com/dstl/YAWNING-TITAN>`_), and help bridge the Sim-to-Real gap into Secondary level environments.
 
 What is PrimAITE built with
 --------------------------------------

pyproject.toml

@@ -81,3 +81,9 @@ order_by_type = "False"
 
 [tool.black]
 line-length = 120
+
+[project.urls]
+Homepage = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE"
+Documentation = "https://Autonomous-Resilient-Cyber-Defence.github.io/PrimAITE/"
+Repository = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE"
+Changelog = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/blob/dev/CHANGELOG.md"

setup.cfg

@@ -0,0 +1,4 @@
+[metadata]
+url = https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE
+author = Defence Science and Technology Laboratory UK
+author_email = oss@dstl.gov.uk