TR-3756 Integrate Honeypatch tool, adapt documentation

dynatrace-oss · Jul 30, 2024 · d51a836 · d51a836
1 parent c8ce8c7
commit d51a836
Show file tree

Hide file tree

Showing 31 changed files with 2,435 additions and 126 deletions.
diff --git a/.gitignore b/.gitignore
@@ -24,3 +24,20 @@ scratchpad.ipynb
 
 # Built Visual Studio Code Extensions
 *.vsix
+
+#################################################################################################
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -73,69 +73,73 @@ repos:
       - id: isort
         name: sort imports with isort
         args: ["--settings-path", "./src/honeyback/pyproject.toml"]
-        files: ^src\/honeyback\/.*\.py$
+        files: ^src\/(honeyback|honeypatch)\/.*\.py$
   - repo: https://github.com/ambv/black
     rev: 24.4.2
     hooks:
       - id: black
         name: format files with black
         args: ["--config", "./src/honeyback/pyproject.toml"]
-        files: ^src\/honeyback\/.*\.py$
+        files: ^src\/(honeyback|honeypatch)\/.*\.py$
         language_version: python3
   - repo: https://github.com/PyCQA/flake8
     rev: 7.1.0
     hooks:
       - id: flake8
-        name: lint files with flake8
+        name: lint files with flake8 (honeyquest)
         args: ["--config", "./src/honeyback/tox.ini"]
         files: ^src\/honeyback\/.*\.py$
         additional_dependencies:
           - flake8-docstrings
           - flake8-rst-docstrings
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.0
+    hooks:
+      - id: flake8
+        name: lint files with flake8 (honeypatch)
+        args: ["--config", "./src/honeypatch/tox.ini"]
+        files: ^src\/honeypatch\/.*\.py$
+        additional_dependencies:
+          - flake8-docstrings
+          - flake8-rst-docstrings
   - repo: local
     hooks:
       - id: pylint
-        name: lint files with pylint
+        name: lint files with pylint (honeyback)
         entry: poetry run -C ./src/honeyback pylint --rcfile ./src/honeyback/pyproject.toml -sn -rn
         language: system
         files: ^src\/honeyback\/.*\.py$
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.0
+  - repo: local
+    hooks:
+      - id: pylint
+        name: lint files with pylint (honeypatch)
+        entry: poetry run -C ./src/honeypatch pylint --rcfile ./src/honeypatch/pyproject.toml -sn -rn
+        language: system
+        files: ^src\/honeypatch\/.*\.py$
+  - repo: local
     hooks:
       - id: mypy
-        name: check types with mypy
-        args: ["--config-file", "./src/honeyback/pyproject.toml"]
+        name: check types with mypy (honeyback)
+        entry: poetry run -C ./src/honeyback mypy --config-file ./src/honeyback/pyproject.toml ./src/honeyback
+        language: system
+        pass_filenames: false
         files: ^src\/honeyback\/.*\.py$
-        additional_dependencies:
-          # packages with built-in type stubs
-          - numpy>=1.26.4,<2.0
-          - dagster>=0.14.20,<1.0
-          - fastapi>=0.111.1,<1.0
-          - pydantic>=2.8.2,<3.0
-          - pydantic-settings>=2.3.4,<3.0
-          - typer>=0.12.3,<1.0
-          - uvicorn>=0.30.3,<1.0
-          # official type stubs
-          - boto3-stubs[essential]<=1.34.145,<2.0
-          - pandas-stubs>=1.5.3,<2.0
-          # third-party type stubs
-          - types-cffi>=1.16,<2.0
-          - types-colorama>=0.4,<1.0
-          - types-croniter>=2.0,<3.0
-          - types-decorator>=5.1,<6.0
-          - types-jsonschema>=4.23,<5.0
-          - types-protobuf>=3.20,<4.0
-          - types-psutil>=6.0,<7.0
-          - types-Pygments>=2.18,<3.0
-          - types-python-dateutil>=2.9,<3.0
-          - types-pytz>=2024,<2025
-          - types-pywin32>=306,<307
-          - types-PyYAML>=6.0,<7.0
-          - types-requests>=2.32,<3.0
-          - types-setuptools>=70.3,<71
-          - types-six>=1.16,<2.0
-          - types-toposort>=1.10,<2.0
-          - types-tqdm>=4.66,<5.0
+  - repo: local
+    hooks:
+      - id: mypy
+        name: check types with mypy (honeypatch)
+        entry: poetry run -C ./src/honeypatch mypy --config-file ./src/honeypatch/pyproject.toml ./src/honeypatch/honeypatch ./src/honeypatch/tests
+        language: system
+        pass_filenames: false
+        files: ^src\/honeypatch\/.*\.py$
+  - repo: local
+    hooks:
+      - id: mypy
+        name: test with pytest (honeypatch)
+        entry: poetry run -C ./src/honeypatch pytest -v --cov=honeypatch ./src/honeypatch
+        language: system
+        pass_filenames: false
+        files: ^src\/honeypatch\/.*\.py$
 
   # javascript files
   - repo: local

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -6,10 +6,5 @@
     "**/.mypy_cache": true,
     "**/.pytest_cache": true
   },
-  "flake8.args": [
-    "--config=${workspaceFolder}/src/honeyback/tox.ini"
-  ],
-  "[github-actions-workflow]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  }
+  "flake8.cwd": "${fileDirname}"
 }
diff --git a/README.md b/README.md
@@ -90,14 +90,14 @@ You need the following toolchain installed:
 - [Poetry](https://python-poetry.org/docs/#installation) for Python dependency management
 - [pre-commit](https://pre-commit.com/#install) for the pre-commit hooks
 
-First, install the frontend dependencies.
+First, install Honeyfront (frontend for Honeyquest) dependencies.
 
 ```sh
 cd ./src/honeyfront
 npm install
 ```
 
-Then, install the backend dependencies.
+Then, install Honeyback (backend for Honeyquest) dependencies.
 Backend dependencies are split into multiple groups:
 
 - `main` covers everything for Honeyquest and Dagster to run
@@ -107,16 +107,26 @@ Backend dependencies are split into multiple groups:
 
 ```sh
 cd ./src/honeyback
+poetry shell
 poetry install --with hooks,analytics
 ```
 
+Then, install Honeypatch dependencies.
+Note that this is a separate Poetry environment.
+
+```sh
+cd ./src/honeypatch
+poetry shell
+poetry install
+```
+
 Then, back in the root directory, install the pre-commit hooks.
 
 ```sh
 pre-commit install
 ```
 
-### Start the backend and frontend
+### Start Honeyquest
 
 The backend exposes a REST API to serve the queries.
 Don't forget to specify the folder that holds the query database.
@@ -143,6 +153,18 @@ Then, navigate to 🌍 [localhost:3000](http://localhost:3000) in your browser.
 Answers from users are stored in a tempory directory that is printed to the console.
 Refer to the [Configuration](#%EF%B8%8F-configuration) section to specify a different location.
 
+### Start Honeypatch
+
+Honeypatch is stand-alone tool to inject traps into arbitrary, text-based payload.
+Start the program and read the help message.
+
+```sh
+cd ./src/honeypatch
+poetry run honeypatch --help
+```
+
+For more usage instructions, refer to the 📄 [HONEYPATCH.md](./docs/HONEYPATCH.md) document.
+
 ## ⚙️ Configuration
 
 ### Configure the query database
@@ -203,8 +225,6 @@ This is useful during development with only a small example dataset to test the
 
 ## ⚖️ License and Attribution
 
-> ℹ️ This product is not officially supported by Dynatrace.
-
 - The source code is licensed under [Apache 2.0](./LICENSE.txt)
 - The query database found in 📂 [`./querydb`](./querydb) is licensed under [ODbL 1.0](./data/LICENSE.txt)
 - The results from our human subject experiment found in 📂 [`./dataset`](./dataset) are licensed under [CC BY 4.0](./dataset/LICENSE.txt)
@@ -219,3 +239,7 @@ If you use Honeyquest, our query database, or our experimental results, please c
 > In The 27th International Symposium on Research in Attacks, Intrusions and Defenses (RAID 2024),
 > September 30-October 02, 2024, Padua, Italy. ACM, New York, NY, USA, 20 pages.
 > <https://doi.org/10.1145/3678890.3678897>
+
+---
+
+_**Note:** Honeyquest is not officially supported by Dynatrace._
diff --git a/docs/HONEYPATCH.md b/docs/HONEYPATCH.md
@@ -0,0 +1,26 @@
+# Honeypatch
+
+Honeypatch is stand-alone tool to inject traps into arbitrary, text-based payload.
+
+> [!IMPORTANT]
+> Honeypatch is still in development and only in a proof-of-concept stage.
+> It is not integrated with the rest of Honeyquest yet.
+
+## 🚀 Usage
+
+List all available honeywire templates.
+
+```sh
+honeypatch list -p ./querydb/honeyaml
+```
+
+Inject additional headers into HTTP responses.
+
+```sh
+honeypatch inject -p ./querydb/honeyaml -w httpheader-apiserver ./docs/examples/http-response.txt
+honeypatch inject -p ./querydb/honeyaml -w httpheader-devtoken ./docs/examples/http-response.txt
+```
+
+### List of available arguments
+
+Please refer to the `--help` command for more information.
diff --git a/docs/examples/http-response.txt b/docs/examples/http-response.txt
@@ -0,0 +1,9 @@
+HTTP/1.1 200 OK
+Date: Mon, 23 May 2005 22:38:34 GMT
+Content-Type: text/html; charset=UTF-8
+Content-Length: 155
+Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT
+Server: Apache/1.3.3.7 (Unix) (Red-Hat/Linux)
+ETag: "3f80f-1b6-3e1cb03b"
+Accept-Ranges: bytes
+Connection: close
diff --git a/querydb/honeyaml/httpheader.yml b/querydb/honeyaml/httpheader.yml
@@ -0,0 +1,17 @@
+honeywire:
+  kind: httpheader
+  name: httpheader-apiserver
+  description: Adds an HTTP header that hints at some API server location
+  operations:
+    - op: add
+      key: X-Kube-ApiServer
+      value: /hko/api
+---
+honeywire:
+  kind: httpheader
+  name: httpheader-devtoken
+  description: Adds an HTTP header that looks like a JWT developer token (secret 'honeypatch' was used for the signature)
+  operations:
+    - op: add
+      key: X-DevToken
+      value: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjMwZDk4NGI4Iiwicm9sZSI6ImNsdXN0ZXIifQ.J2c1XH2RsXDjaWJhCHSWR4bBNxEm7l2Q7WxrlG2vph4
diff --git a/src/honeyback/honeyquest/__main__.py b/src/honeyback/honeyquest/__main__.py
@@ -83,8 +83,9 @@ def ui_cli(
     # TODO: RT-2490 let pydantic handle this rule
     # the fully-resolved settings object may only have a data path or url, not none, not both
     if not bool(settings.honeyquest_data) ^ bool(settings.honeyquest_data_url):
-        typer.echo("Please specify either --data or --data-url via the CLI or the environment")
-        raise typer.Exit(1)
+        raise typer.BadParameter(
+            "please specify either --data or --data-url via the CLI or the environment"
+        )
 
     run_server(settings, debug=debug)