{"id":22712066,"url":"https://github.com/dynatrace-oss/honeyquest","last_synced_at":"2025-04-12T13:51:26.079Z","repository":{"id":253943305,"uuid":"590495181","full_name":"dynatrace-oss/honeyquest","owner":"dynatrace-oss","description":"Honeyquest is a cyber security game that asks humans to distinguish neutral, risky, and deceptive payloads. Honeyquest presents participants with realistic web application vignettes (\"queries\"). Participants are asked to think like a hacker and tell us their next move.","archived":false,"fork":false,"pushed_at":"2024-08-20T12:17:54.000Z","size":1585,"stargazers_count":6,"open_issues_count":9,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T08:23:51.904Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://honeyquest.cns.research.dynatracelabs.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dynatrace-oss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-18T14:49:51.000Z","updated_at":"2024-11-24T11:41:13.000Z","dependencies_parsed_at":"2024-08-21T03:49:57.647Z","dependency_job_id":null,"html_url":"https://github.com/dynatrace-oss/honeyquest","commit_stats":null,"previous_names":["dynatrace-oss/honeyquest"],"tags_count":2,"template":false,"template_full_name":"dynatrace-oss/template-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynatrace-oss%2Fhoneyquest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynatrace-oss%2Fhoneyquest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynatrace-oss%2Fhoneyquest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynatrace-oss%2Fhoneyquest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dynatrace-oss","download_url":"https://codeload.github.com/dynatrace-oss/honeyquest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248575690,"owners_count":21127247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-10T13:09:18.624Z","updated_at":"2025-04-12T13:51:26.050Z","avatar_url":"https://github.com/dynatrace-oss.png","language":"Python","funding_links":[],"categories":["Research","Uncategorized"],"sub_categories":["Code Repositories","Uncategorized"],"readme":"\u003c!-- markdownlint-disable no-inline-html first-line-h1 --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Honeyquest Logo\" width=\"128px\" src=\"./src/honeyfront/src/images/HoneyquestLogo.svg\" /\u003e\n\u003c/p\u003e\n\n# Honeyquest\n\nHoneyquest is a cyber security game that asks humans to distinguish neutral, risky, and deceptive payloads.\nHoneyquest presents participants with realistic web application vignettes (\"queries\").\nParticipants are asked to think like a hacker and tell us their next move.\n\nHoneyquest can be used to evaluate what vulnerabilities and cyber traps are most attractive to attackers.\n\n- 🚀 **Demo** — [honeyquest.cns.research.dynatracelabs.com](https://honeyquest.cns.research.dynatracelabs.com)\n\u003c!-- - 📜 **Paper** — [Honeyquest: Rapidly Measuring the Enticingness of Cyber Deception Techniques with Code-based Questionnaires](https://doi.org/10.1145/3678890.3678897) --\u003e\n\n![Honeyquest user interface](./docs/images/honeyquest.gif)\n\n## 🐳 Quickstart\n\nUse the Docker image to start Honeyquest.\nAppend the `--help` argument to see all available options.\n\n```sh\ndocker run -p 3000:3000 ghcr.io/dynatrace-oss/honeyquest -u https://raw.githubusercontent.com/dynatrace-oss/honeyquest/main/.github/hostedfiles/querydb.tar.gz\n```\n\nThen, navigate to 🌍 [localhost:3000](http://localhost:3000) in your browser.\n\n## 📦 Project Structure\n\n- 🚀 Want to **TRY OUT** Honeyquest? Visit our live demo at [honeyquest.cns.research.dynatracelabs.com](https://honeyquest.cns.research.dynatracelabs.com) today.\n- 📊 Want to **ANALYZE** the results from our human subject experiment? Navigate to the 📂 [`./dataset`](./dataset) directory.\n- 🎨 Want to **CREATE** your own query database? Start with the 📄 [QUERY_DATABASE](./docs/QUERY_DATABASE.md) document.\n- 💻 Want to **DEVELOP** the Honeyquest application locally? Follow the [Developer Guide](#-developer-guide) below.\n- ☁️ Want to **DEPLOY** Honeyquest to AWS? Refer to the 📄 [DEPLOYMENT](./docs/DEPLOYMENT.md) document.\n- ⚖️ Want to **CITE** Honeyquest, our datasets, or our paper? Head to the [License and Attribution](#%EF%B8%8F-license-and-attribution) section.\n\nHoneyquest needs a query database to run. The query database contains the questions that are presented to the users.\nOur queries are stored in the 📂 [`./querydb`](./querydb) directory. You can also create your own queries.\nQueries are just YAML files with a specific structure that is described in the 📄 [QUERY_DATABASE](./docs/QUERY_DATABASE.md) document.\nTo automate the creation of queries, we also provide a few [Dagster](https://dagster.io/) jobs\nwhich are described in the 📄 [QUERY_CREATION](./docs/QUERY_CREATION.md) document.\nSome queries are created by \"patching\" existing queries with our separate 📂 [`./src/honeypatch`](./src/honeypatch) tool.\nFind a bit of information about Honeypatch in the 📄 [HONEYPATCH](./docs/HONEYPATCH.md) document.\n\nThe Honeyquest application consists of a frontend and a backend process.\nThe frontend is a React application that serves the user interface.\nThe backend is a Python application that exposes a REST API with FastAPI and does all the heavy lifting.\nOur Docker container bundles both the frontend and the backend into a single container for easy deployment.\n\nDuring our study we ran a human subject experiment with 47 participants,\nwho submitted a total of 3,669 responses to our queries (and placed 6,659 individual marks).\nWe dataset is freely available for further research and analysis.\nThe dataset and a description of it is stored in the 📂 [`./dataset`](./dataset/README.md) directory.\nAlso, we provide a few Jupyter notebooks and Python scripts that we used to analyze the results in the\n📂 [`./src/honeyback/honeyquest/data/notebooks`](./src/honeyback/honeyquest/data/notebooks) directory.\n\n```mermaid\ngraph TB;\n  subgraph RESULTS ANALYSIS\n    dataset[\"\u003ctt\u003e\u003csmall\u003e/dataset\u003c/small\u003e\u003c/tt\u003e\\n\u003cstrong\u003eHUMAN SUBJECT\u003c/strong\u003e\\n\u003cstrong\u003eSTUDY RESULTS\u003c/strong\u003e\"]\n    notebooks[\"\u003ctt\u003e\u003csmall\u003e/src/honeyback\u003c/small\u003e\u003c/tt\u003e\\n\u003ctt\u003e\u003csmall\u003e/honeyquest/data/notebooks\u003c/small\u003e\u003c/tt\u003e\\nJupyter Notebooks\"]\n  end\n\n  subgraph \"HONEYQUEST\"\n    direction TB\n    frontend[\"\u003ctt\u003e\u003csmall\u003e/src/honeyfront\u003c/small\u003e\u003c/tt\u003e\\nReact Frontend\"]\n    backend[\"\u003ctt\u003e\u003csmall\u003e/src/honeyback\u003c/small\u003e\u003c/tt\u003e\\nPython Backend\"]\n    frontend --\u003e|\u003ctt\u003e\u003csmall\u003e/api\u003c/small\u003e\u003c/tt\u003e| backend;\n  end\n\n  subgraph QUERY CREATION\n    queries[\"\u003ctt\u003e\u003csmall\u003e/querydb\u003c/small\u003e\u003c/tt\u003e\\n\u003cstrong\u003eQUERY DATABASE\u003c/strong\u003e\"]\n    dagster[\"\u003ctt\u003e\u003csmall\u003e/src/honeyback\u003c/small\u003e\u003c/tt\u003e\\n\u003ctt\u003e\u003csmall\u003e/honeyquest/data/jobs\u003c/small\u003e\u003c/tt\u003e\\nCreate New Queries\"]\n    honeypatch[\"\u003ctt\u003e\u003csmall\u003e/src/honeypatch\u003c/small\u003e\u003c/tt\u003e\\nInject Traps\"]\n  end\n```\n\n## 💻 Developer Guide\n\nPlanning to make changes to the source code or just want to run Honeyquest locally? Read on.\n\n### Prerequisites\n\nYou need the following toolchain installed:\n\n- [Node.js 20](https://nodejs.org/en/download/) for the frontend app\n- [Python 3.10](https://www.python.org/downloads/) for the backend API\n- [Poetry](https://python-poetry.org/docs/#installation) for Python dependency management\n- [pre-commit](https://pre-commit.com/#install) for the pre-commit hooks\n\nFirst, install Honeyfront (frontend for Honeyquest) dependencies.\n\n```sh\ncd ./src/honeyfront\nnpm install\n```\n\nThen, install Honeyback (backend for Honeyquest) dependencies.\nBackend dependencies are split into multiple groups:\n\n- `main` covers everything for Honeyquest and Dagster to run\n- `hooks` (optional) contains pre-commit hooks, linters, formatters, and type checkers\n- `analytics` (optional) contains packages to analyze the data and create figures\n- `docker` (optional) contains a process manager needed only inside the Docker container\n\n```sh\ncd ./src/honeyback\npoetry shell\npoetry install --with hooks,analytics\n```\n\nThen, install Honeypatch dependencies.\nNote that this is a separate Poetry environment.\n\n```sh\ncd ./src/honeypatch\npoetry shell\npoetry install\n```\n\nThen, back in the root directory, install the pre-commit hooks.\n\n```sh\npre-commit install\n```\n\n### Start Honeyquest\n\nThe backend exposes a REST API to serve the queries.\nDon't forget to specify the folder that holds the query database.\nFor more options, take a look at the CLI help or head to the [Configuration](#%EF%B8%8F-configuration) section.\nStart the backend API with the following command:\n\n```sh\ncd ./src/honeyback\npoetry run honeyquest --data ../../querydb\n```\n\nThe frontend serves the user interface.\nDuring development, Vite will transparently proxy requests to `/api` to the backend REST API.\nDuring production, an NGINX server in the Docker container will route these requests instead.\nStart the frontend with the following command:\n\n```sh\ncd ./src/honeyfront\nnpm run dev\n```\n\nThen, navigate to 🌍 [localhost:3000](http://localhost:3000) in your browser.\n\nAnswers from users are stored in a tempory directory that is printed to the console.\nRefer to the [Configuration](#%EF%B8%8F-configuration) section to specify a different location.\n\n### Start Honeypatch\n\nHoneypatch is stand-alone tool to inject traps into arbitrary, text-based payload.\nStart the program and read the help message.\n\n```sh\ncd ./src/honeypatch\npoetry run honeypatch --help\n```\n\nFor more usage instructions, refer to the 📄 [HONEYPATCH.md](./docs/HONEYPATCH.md) document.\n\n## ⚙️ Configuration\n\n### Configure the query database\n\nThe backend API needs to be told where to find the query database.\nThe query database contains the questions that are presented to the users.\n\nThe easiest way is to tell Honeyquest to download a `.tar.gz` compressed dataset from a public URL\nand extract it on the fly with the `--data-url` argument (or the `HONEYQUEST_DATA_URL` environment variable).\nThe following command downloads our query database from GitHub and starts the backend:\n\n```sh\nhoneyquest --data-url https://raw.githubusercontent.com/dynatrace-oss/honeyquest/main/.github/hostedfiles/querydb.tar.gz\n```\n\nYou can also pass the `--data` argument (or the `HONEYQUEST_DATA` environment variable)\nto the CLI with the path to the query database. The following command uses our query database and starts the backend:\n\n```sh\nhoneyquest --data ./querydb\n```\n\nIf you want to create your own query database, refer to the 📄 [QUERY_DATABASE.md](./docs/QUERY_DATABASE.md) document.\n\n### List of available arguments and environment variables\n\n| Environment Variable                            | CLI Argument         | Description                                          | Default      |\n| ----------------------------------------------- | -------------------- | ---------------------------------------------------- | ------------ |\n| `HONEYQUEST_DATA` _(required)_ \u003csup\u003e1\u003c/sup\u003e     | `-d` or `--data`     | Directory with the query database                    | not set      |\n| `HONEYQUEST_DATA_URL` _(required)_ \u003csup\u003e1\u003c/sup\u003e | `-u` or `--data-url` | URL with the query database as a `.tar.gz` file      | not set      |\n| `HONEYQUEST_RESULTS`                            | `-r` or `--results`  | Directory for user profiles, responses, and feedback | temporary    |\n| `HONEYQUEST_INDEX`                              | `-i` or `--index`    | Name of the query index \u003csup\u003e2\u003c/sup\u003e                 | `main`       |\n| `ADMIN_TOKEN` _(recommended)_                   | `--admin-token`      | Token for the admin panel                            | random token |\n| `COOKIE_SECRET` _(recommended)_                 | `--cookie-secret`    | Secret to sign session cookies \u003csup\u003e3\u003c/sup\u003e          | random token |\n| `COMPRESS_RESULTS`                              | `--compress`         | Compress results with gzip                           | `false`      |\n| `SAMPLE_DUPLICATES`                             | `--duplicates`       | Sample duplicate queries \u003csup\u003e4\u003c/sup\u003e                | `false`      |\n| `COOKIE_EXPIRE_DAYS`                            |                      | Maximum age of the browser cookie                    | `365`        |\n| `SESSION_TIMEOUT_MINS`                          |                      | Clusters user responses in multiple (session) files  | `60`         |\n| `API_BURST_LIMIT`                               |                      | Capacity of the leaky bucket for rate limiting       | `10`         |\n| `API_RATE_LIMIT`                                |                      | Refill rate of the leaky bucket for rate limiting    | `1`          |\n|                                                 | `--debug`            | Enable development mode                              | `false`      |\n|                                                 | `--help`             | Shows the help text on the console                   |              |\n\n\u003csup\u003e1\u003c/sup\u003e You must set only one of `HONEYQUEST_DATA` or `HONEYQUEST_DATA_URL` to start Honeyquest, not both.\n\n\u003csup\u003e2\u003c/sup\u003e The query database not only contains the questions but also one or more query indices.\nQuery indices define what questions are shown to the user, and in what order.\nThis argument allows to select a different index from the query database. If not set, the default index `main` is used.\nIf no `main` index is found, but there is only one index, that index is used. Otherwise, an error is thrown.\nRefer to the 📄 [QUERY_DATABASE.md](./docs/QUERY_DATABASE.md) document for more information.\n\n\u003csup\u003e3\u003c/sup\u003e You should set some secret to sign the session cookies to prevent session tampering.\nIf you do not set this, a random token is generated on startup and printed to the console.\nIf you ever change this, all existing sessions will be invalidated.\n\n\u003csup\u003e4\u003c/sup\u003e Allows users to submit the answers to the same query multiple times.\nThis is useful during development with only a small example dataset to test the application.\n\n## ⚖️ License and Attribution\n\n- The source code is licensed under [Apache 2.0](./LICENSE.txt)\n- The query database found in 📂 [`./querydb`](./querydb) is licensed under [ODbL 1.0](./data/LICENSE.txt)\n- The results from our human subject experiment found in 📂 [`./dataset`](./dataset) are licensed under [CC BY 4.0](./dataset/LICENSE.txt)\n\nPlease note certain portions of source code, as identified in remarks, are provided under the Creative Commons BY-SA or the MIT license.\nIn each of the remarks, we have provided attribution to the original creators and other attribution parties.\n\nIf you use Honeyquest, our query database, or our experimental results, please cite the following work:\n\n\u003e Mario Kahlhofer, Stefan Achleitner, Stefan Rass, and René Mayrhofer. 2024.\n\u003e Honeyquest: Rapidly Measuring the Enticingness of Cyber Deception Techniques with Code-based Questionnaires.\n\u003e In The 27th International Symposium on Research in Attacks, Intrusions and Defenses (RAID 2024),\n\u003e September 30-October 02, 2024, Padua, Italy. ACM, New York, NY, USA, 20 pages.\n\u003e \u003chttps://doi.org/10.1145/3678890.3678897\u003e\n\n---\n\n_**Note:** Honeyquest is not officially supported by Dynatrace._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynatrace-oss%2Fhoneyquest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdynatrace-oss%2Fhoneyquest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynatrace-oss%2Fhoneyquest/lists"}