Feature/fix readme (#21)

Co-authored-by: kroskinskiis <ivo.kroskinski@tno.nl>
Co-authored-by: jp <jan-paul.konijn@tno.nl>

Author: 3 people

.gitignore

@@ -1,3 +1,3 @@
 .vscode/settings.json
 **/__pycache__/
-.env
+**/env/**

README.md

@@ -1,43 +1,86 @@
 # SOARCA Fin Library
 A Python implementation for the SOARCA FIN, compatible with: SOARCA the TNO orchestrator for Open-C2, CACAO and STIX
+For more information about the SOARCA, we refer the reader to the [website](https://cossas.github.io/SOARCA/) of the SOARCA project.
+For more in depth documentation, see the documentation page on here.
 
-## building / starting / stopping  
-### Requirements
+## Quick Use
+
+Usage of this SOARCA Fin Library is described [here](https://cossas.github.io/SOARCA/docs/soarca-extensions/fin-python-library/).
+
+## Example 
+
+An example is given in this project in the file `examples/pong_example.py`
+
+## Contributing
+Want to contribute to this project? Please keep in mind the following [rules](https://cossas.github.io/SOARCA/docs/contribution-guidelines/):
+- This repository uses git **rebase** strategy
+- For each PR, there should be at least one issue
+- Make sure all tests pass (including lint errors)
+
+### Running this repository
+#### Requirements
  - Python3
+ - Poetry
 
-### Setup
-Install requirements
+#### Setup
+##### Env File
+In order to run the project, create an `.env` file in the root of the project with the following entries:
 ```bash
-pip3 install -r requirements.txt
-```
-Create .env file with the following entries:
-```
+MQTT_BROKER = "{INSERT_MQTT_BROKER_URL_HERE}"
+MQTT_PORT = "{INSERT_MQTT_PORT_HERE}"
 MQTT_USERNAME = "{INSERT_USERNAME_HERE}"
 MQTT_PASSWD = "{INSERT_PASSWORD_HERE}"
 ```
+If no `.env` file is specified, the following default values will be used:
+```bash
+MQTT_BROKER = "localhost"
+MQTT_PORT = "1883"
+MQTT_USERNAME = "soarca"
+MQTT_PASSWD = "password"
+```
 
-
-### Quick Run
+##### Dependencies
+To handle dependencies in this project, the package Poetry is used.
+To install Poetry execute the following command:
 ```bash
-python3 main.py
+pip3 install poetry
 ```
 
-### Setup SOARCA Capabilities
-To register a fin to SOARCA, first create a SoarcaFin object pass the fin_id in the constructor.
-Call `set_config_MQTT_server()` to set the required configurations for the fin to connect to the MQTT broker.
-For each capability to be registered, call `create_fin_capability()`. The capability callback funtion should return an object of type `ResultStructure`.
-When all capabilities are initialized, call `start_fin()` for the SOARCA Fin to connect to the MQTT broker and register itself to SOARCA.
+To install the dependencies from the `pyproject.toml` either enter a poetry shell, create a virtual environment or use poetry run.
+To enter a poetry shell execute the following command in the root of the project:
+```bash
+poetry shell
+```
 
+To install the dependencies in a poetry shell or create a virtual environment, run:
+```bash
+poetry install
+```
 
-## Documentation
-For documentation about the fin protocol we refer the reader to de documention page of [SOARCA](https://cossas.github.io/SOARCA/docs/soarca-extensions/fin-protocol/)
+### Quick Run
+To quick run the project, either run it through poetry run or a poetry shell.
+#### Poetry Run
+```bash
+poetry run python examples/pong_example.py
+```
 
-For class diagrams and example sequence diagrams of the Fin implementation [plantUML](https://plantuml.com/) is used.
+#### Poetry Shell
+```bash
+python examples/pong_example.py
+```
 
-### Application Layout
-The main object of the application is the `SoarcaFin` object, which is responsible for configuring and creating and controlling the capabilities.
-The SoarcaFin creates `MQTTClient`s for each capability registered, plus one for registering, unregistering and controlling the fin.
-`MQTTClient`s each have their own connection to the MQTT Broker and own `Parser` and `Executor` objects.
-The `Parser` object parsers the raw MQTT messages and tries to convert them to one of the objects in `src/models`.
-The `Executor` runs in their own thread and handles the actual execution of the messages.
-The `Executor` polls a thread-safe queue for new messages and performs IO operations, such as sending messages to the MQTT broker and calling capability callbacks.
+### Running tests
+To run the tests in this repository use:
+```bash
+poetry run python -m unittest
+``` 
+To run python linter, first install pylint and then run pylint with the following arguments:
+```bash
+poetry add pylint &&
+poetry run pylint --disable=R,C $(git ls-files '*.py')
+```
+To format the code base, first install ruff and then run ruff:
+```bash
+poetry add ruff &&
+poetry run ruff format
+```

examples/gettingstarted.md

@@ -0,0 +1,14 @@
+# Getting started
+
+
+### prerequisites 
+To install sourca-fin-library you can use the following command:
+
+```bash
+pip install -r requirements.txt
+```
+### Quick run
+
+```bash
+python3 pong_example.py
+```

soarca_fin_python_library/main.py examples/pong_example.pysoarca_fin_python_library/main.py renamed to examples/pong_example.py

@@ -1,5 +1,4 @@
 import os
-import logging as log
 from dotenv import load_dotenv
 
 from soarca_fin_python_library.soarca_fin import SoarcaFin
@@ -16,44 +15,57 @@
 
 
 def capability_pong_callback(command: Command) -> ResultStructure:
-    log.info("Received ping, returning pong!")
-    out = Variable(
+    print("Received ping, returning pong!")
+
+    result = Variable(
         type=VariableTypeEnum.string,
         name="pong_output",
         description="If ping, return pong",
         value="pong",
         constant=True,
         external=False)
+
     context = command.command.context
+
     return ResultStructure(
-        state="success", context=context, variables={"result": out})
+        state="success", context=context, variables={"result": result})
 
 
 def main(mqtt_broker: str, mqtt_port: int, username: str, password: str) -> None:
 
-    agent = AgentStructure(name="soarca-fin--123")
+    finId = "soarca-fin--pingpong-f877bb3a-bb37-429e-8ece-2d4286cf326d"
+    agentName = "soarca-fin-pong-f896bb3b-bb37-429e-8ece-2d4286cf326d"
+    externalReferenceName = "external-reference-example-name"
+    capabilityId = "mod-pong--e896aa3b-bb37-429e-8ece-2d4286cf326d"
+
+    # Create AgentStructure
+    agent = AgentStructure(
+        name=agentName)
 
-    external_reference = ExternalReference(name="external-reference-name")
+    # Create ExternalReference
+    external_reference = ExternalReference(name=externalReferenceName)
 
+    # Create StepStructure
     step_structure = StepStructure(
         name="step_name",
         description="step description",
         external_references=[external_reference],
-        command="test-command",
-        target="123456")
+        command="pong",
+        target=agentName)
 
+    # Create CapabilityStructure
     capability_structure = CapabilityStructure(
-        capability_id="mod-virustotal--e896aa3b-bb37-429e-8ece-2d4286cf326d",
+        capability_id=capabilityId,
         type=WorkFlowStepEnum.action,
-        name="capability_name",
+        name="Ping Pong capability",
         version="0.0.1",
         step={
             "test": step_structure},
         agent={
             "testagent": agent})
 
     # Create Soarca fin
-    fin = SoarcaFin("123456789")
+    fin = SoarcaFin(finId)
     # Set config for MQTT Server
     fin.set_config_MQTT_server(mqtt_broker, mqtt_port, username, password)
     # Register Capabilities
@@ -63,8 +75,6 @@ def main(mqtt_broker: str, mqtt_port: int, username: str, password: str) -> None
 
 
 if __name__ == "__main__":
-    log.basicConfig()
-    log.getLogger().setLevel(log.DEBUG)
     load_dotenv()
     MQTT_BROKER = os.getenv("MQTT_BROKER", "localhost")
     MQTT_PORT = int(os.getenv("MQTT_PORT", "1883"))

examples/requirement.txt

@@ -0,0 +1 @@
+soarca-fin-library