{"id":15023891,"url":"https://github.com/sap/cloud-active-defense","last_synced_at":"2026-04-07T10:03:32.121Z","repository":{"id":229005524,"uuid":"774347865","full_name":"SAP/cloud-active-defense","owner":"SAP","description":"Add a layer of active defense to your cloud applications.","archived":false,"fork":false,"pushed_at":"2025-01-22T10:50:23.000Z","size":22658,"stargazers_count":88,"open_issues_count":0,"forks_count":9,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-01-30T00:51:11.090Z","etag":null,"topics":["cybersecurity","deception","decoy","honeytoken","infosec","security"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/SAP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-19T11:48:45.000Z","updated_at":"2025-01-28T19:28:10.000Z","dependencies_parsed_at":"2024-03-25T11:24:36.051Z","dependency_job_id":"df69cef1-f8f7-4709-9eb0-65e183d2aceb","html_url":"https://github.com/SAP/cloud-active-defense","commit_stats":null,"previous_names":["sap/cloud-active-defense"],"tags_count":9,"template":false,"template_full_name":"SAP/repository-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAP%2Fcloud-active-defense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAP%2Fcloud-active-defense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAP%2Fcloud-active-defense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAP%2Fcloud-active-defense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SAP","download_url":"https://codeload.github.com/SAP/cloud-active-defense/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237191463,"owners_count":19269710,"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":["cybersecurity","deception","decoy","honeytoken","infosec","security"],"created_at":"2024-09-24T19:59:34.940Z","updated_at":"2025-10-19T18:30:56.209Z","avatar_url":"https://github.com/SAP.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n\n![Static Badge](https://img.shields.io/badge/Mission-detect,_divert,_deter_cybercriminals-purple) [![REUSE status](https://api.reuse.software/badge/github.com/SAP/cloud-active-defense)](https://api.reuse.software/info/github.com/SAP/cloud-active-defense)\n\n\u003c/div\u003e\n\n# cloud-active-defense\n\nAdd a layer of active defense to your cloud applications.\n\n# 5' usage demo (turn on the sound!)\n\n[!](https://github.com/SAP/cloud-active-defense/assets/20401195/472015658-0a4baf61-17a1-48c2-970b-75a78ed73a63)\n\n## Table of Contents\n1. [About this project](#About-this-project)\n2. [Requirements](#requirements)\n3. [Quickstart](#quickstart)\n4. [Architecture and Philosophy](#Architecture-and-Philosophy)\n5. [Configuration and advanced topics](#Configuration-and-advanced-topics)\n6. [Support, Feedback, Contributing](#support-feedback-contributing)\n7. [Security / Disclosure](#security--disclosure)\n8. [On the TODO list](#on-the-todo-list)\n9. [Code of Conduct](#Code-of-Conduct)\n10. [Licensing](#Licensing)\n\n# About this project\nCloud active defense lets you deploy decoys right into your cloud applications, putting adversaries into a dilemma: to hack or not to hack?\n  * If they interact with any of your decoys, they are instantly detected.\n  * If they refrain, they reduce their ability to attack, making your applications safer.\n\nYou win in either case.\n\n# Requirements\n\n- [Docker 🐳](https://docs.docker.com/get-docker/)\n- [Docker Compose](https://docs.docker.com/compose/install/) (you can do without, but this will make your life easier)\n\n\n## Optional requirements\nIf you want to rebuild the plugin, you'll need these:\n- [Go 1.19+](https://go.dev/doc/install)\n- [TinyGo](https://tinygo.org/getting-started/install/)\n\n\n# Quickstart\n\n1. clone the repo\n\n`git clone https://github.com/SAP/cloud-active-defense.git`\n\n2. start in demo mode\n\n```\ncd cloud-active-defense\ndocker-compose up --build\n```\n\n3. check that it works\n\nAccess the controlpanel at `localhost`\n\nKeycloak will redirect you to its own login page, from here click register and created create a new account (or login if you already have an account)\n![Keycloak register](./assets/keycloak-register.png)\n\nNow that you are logged in keycloak should have redirected you to the controlpanel dashboard\n\nOn the `Decoys`\u003e`list` tab you have a \"default\" decoy to test if everything is working properly\nCheck that decoy to deploy it\n\nVisit `http://localhost:8000` from a web browser. You should be granted by a 'welcome' page. Inpect the network traffic (In Firefox: `CTRL+SHIFT+I`, visit 'Network', then click on the / request), notice the presence of an HTTP Response Header saying `x-cloud-active-defense=ACTIVE`\n\n![x-cloud-active-defense header](./assets/header.png)\n\n## Add a decoy\n\nLet's add a first simple decoy. It won't be very useful but it is easy to understand.\n\n1. open controlpanel at `localhost` and go to `Decoys`\u003e`List` tab\n\n2. import `examples/simple-decoy.json` and check deployed\n\n3. check the `Logs` tab for the following line: `read new config`\n\n4. visit `http://localhost:8000/forbidden`. This should give you an error message `Cannot GET /forbidden`. Check that an alert was sent to `Logs` tab with LOW severity.\n\n![forbidden decoy alert](./assets/alert.png)\n\n## Add a post-authentication decoy\n\nThe decoy we just added might trigger if your application is scanned by bots, but what's more interesting is to detect compromised user accounts. So let's create a decoy which will be visible only to authenticated users.\n\n1. open controlpanel at `localhost` and go to `Decoys`\u003e`List` tab\n\n2. import `examples/post-auth-decoy.json` and check deployed\n\n3. check the console for the following line: `wasm log: read new config`\n\n4. visit `http://localhost:8000/login`. Login as **bob@myapp.com/bob**. Press `CTRL-SHIFT-I` to open the developer tools and navigate to the 'storage' tab. Notice how, upon login, a 'role=user' cookie was injected into your cookie jar.\n\n![injected role cookie](./assets/cookie.png)\n\nModify manually the value of the role cookie by double-clicking its value in the developer view. Set it to 'admin', then refresh the page. Notice that an alert was sent to the console with HIGH severity. Seems that Bob is a hacker or that someone who guessed his not-so-strong password is trying to escalate privileges!\n\n![role decoy alert](./assets/alert2.png)\n\n# Architecture and Philosophy\n\nCloud active defense is about making hacking *painful*. Today, attackers rely on the information provided by the application to successfully exploit it. This information is under our control - and there is no reason not to lie to attackers.\nWe're not the first one to think about deploying deceptive element into applications. The [OWASP AppSensor](https://owasp.org/www-project-appsensor/) project came there first. But adding deceptive traps is an effort that's best kept separate from your application code:\n\n  * developers might not have the time or security skills for that\n  * adding code always bears the risk to introduce new (security!) bugs\n\nOur approach was thus to let applications be protected by introducing a reverse-proxy, reading instructions from a versatile configuration file. No risk to introduce bugs to the application, and easy maintenance.\n\nFor the reverse-proxy, we chose [Envoy](https://www.envoyproxy.io/). At its heart, cloud active defense is simply a plugin for Envoy. We chose Envoy because it's open source, fast, extensible, and because it's a popular choice as a Service Mesh solution. What this means is that cloud active defense can easily be deployed as a side-car if you use a kubernetes platform such as [SAP Kyma](https://kyma-project.io/). We are doing our best to provide a working solution, but consider testing it heavily before using it productively (and please report any issues you discover!)\n\nArchitecture-wise, cloud active defense is a WASM file deployed within Envoy in its own container. As WASM cannot read files from the filesystem, we instead expose the config in the **controlpanel API** service and retrieve it from Envoy via HTTP. In docker, only the default config can be used. When deployed in Kubernetes, each service can have its own config, this is described in its own section.\n\n![Main architecture](./assets/arch.png)\n\nEnvoy receives a request from the **browser** and forwards it to the **application**. Upon receiving the response from the application, Envoy checks if there is something to inject and behaves accordingly. On a subsequent request, Envoy checks if injected elements were interacted with and alerts accordingly.\n\nCloud active defense complements existing solutions such as Intrusion Detection Systems and honeypot-based deception by instrumenting the target web application itself. By adding decoys based on the application's business logic, you can raise high value, true positive alerts that warn your SOC team in real time before any harm is done. If you deploy decoys visible only to authenticated users, you can further detect account impersonation. This approach makes our solution unique.\n\n## Myapp\nMyapp is a demo application which can be used to test how decoys work. It is a simplistic web application with the following features:\n  * `GET /` : the front page, displays 'welcome' if you're not authenticated. Displays a static 'dashboard' page otherwise.\n  * `GET /login` : a form displaying a login field, a password field, and a submit button.\n  * `POST /login` : checks if username is 'bob@myapp.com' and password is 'bob'. It not, sends an error message. If yes, authenticates by setting a (hardcoded) 'SESSION' cookie\n\nThere is no logout mechanism. Delete the SESSION cookie to log out.\n\n## Controlpanel API\nThis API will be the decoy manager for envoy, but also will store the decoys, logs in its database, manage \"customer\" when deployed on kubernetes and manage other configuration for differents application. It can be connected to the controlpanel frontend\n\nEnvoy will send a GET request to the API a few times per minute and update its config accordingly. If running on docker-compose, 'namespace' and 'application' will both be empty strings, thus Envoy will always fetch the content of default config. If running on kubernetes, 'namespace' and 'application' will be properly set, allowing you to define one configuration per application per namespace.\n\n## Envoy\nEnvoy is an open-source reverse proxy. Upon start, it reads the envoy.yaml config file, which loads the cloud-active-defense.wasm plugin. This plugin reads the content of cad-default.json and applies it upon receiving HTTP requests from the browser and HTTP responses from myapp.\n\n# Full architecture\n\n![Full architecture](./assets/arch1.png)\n\nThe full architecture comprises extra containers which achieve the following goals:\n\n## Fluent-bit\nAlerts raised by Envoy are sent to its console log. By configuring 'fluentd' as a logging driver, these alerts are sent to a **fluent-bit** container. Fluent-bit can be seen as a pipe which can collect and forward data. By default, fluent-bit will display the collected data to its own console log and send it to the controlpanel API. Now, fluent-bit can be configured to forward these logs to your favorite monitoring tool, such as Splunk, Loki or Elasticsearch. Please refer to [fluentbit.io](https://docs.fluentbit.io/manual/pipeline/outputs) for details.\n\n## Clone and Exhaust\nOn top of alerting, cloud active defense can be configured to execute an automated response. One such response is to *divert* the adversary to, essentially, a honeypot.\n\nWe pre-defined two such diversion endpoints: **clone** and **exhaust**. As with how **myapp** should be replaced with your own application, these two endpoints should be replaced too if you chose to use diversion as a response mechanism.\n\n### Exhaust\nThink of this endpoint as a *fake facade*. From the outside it looks like your application, but there is nothing behind. The goal of this facade is to exhaust attackers resources against what is basically a wall.\n\nIf, upon detection of an attack, envoy detects that the request to be diverted is not authenticated, then it will forward it to the **exhaust** endpoint instead of **myapp**. The exhaust honeypot can be simply a copy of myapp's publicly reachable pages, with no business logic behind. For the demo, the exhaust app is a copy of myapp without any business logic, meaning that trying to login with valid credentials will be denied. All requests sent to **exhaust** should be considered malicious and are thus logged.\n\n#### (experimental)\nYou can find in the `exhaust` directory an experimental script to clone your own website to make an exhaust. Since this is experimental it may not be perfect. A readme is provided with more explanation is the same directory\n\n### Clone\nThink of this endpoint as a regular *honeypot*. It looks like what is inside your application, but all the content is fake and worthless. The goal of this trap is to further blur the line between what is real and what is not.\n\nIf, upon detection of an attack, envoy detects that the request to divert is authenticated, then it will forward it to the **clone** endpoint instead of **myapp**. The clone honeypot should keep the illusion that the user is logged into the real application, so the clone should be a copy of myapp, except for its data, which should be faked. Creating a believable, fake copy of an application is a complex task that we might visit someday. In the meantime, you may want to deploy a second copy of your **exhaust** application as your **clone**. All requests sent to **clone** should be considered malicious and are thus logged.\n\nPlease refer to our [wiki](https://github.com/SAP/cloud-active-defense/wiki/Detect#respond) for details.\n\n### Controlpanel Frontend\nThe frontend is where you can control and manage the decoys you set and have a better view of the alerts sent by fluentbit. This controlpanel provides a way to add/modify, enable or disable a decoy and display the decoys in a list.\n\n### Keycloak\nKeycloak is an open-source software product to allow single sign-on with identity and access management aimed at modern applications and services. It will manage users for accessing both controlpanel frontend and API. API routes are all protected with an JWT provided and managed by keycloak avoiding broken access control and allowing anyone to read or change decoys for an application\n\n# Configuration and advanced topics\nPlease refer to our [wiki](https://github.com/SAP/cloud-active-defense/wiki) page to learn about decoys in details, and about how to modify the source code.\n\n# Support, Feedback, Contributing\n\nThe code is provided \"as-is\" and will be maintained with a best effort approach.\nLet's make defense a fun topic ! We hope that you'll fall in love with the concept as much as we are and help us break the attack / defense assymmetry.\n\nThis project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/SAP/cloud-active-defense/issues). Contribution and feedback are encouraged and always welcome. \n\nWe are welcoming contributions such as:\n  * bug reports\n  * security improvements\n  * decoy ideas (mimicking existing vulnerabilities such as [CVE-2023-32725](https://nvd.nist.gov/vuln/detail/CVE-2023-32725))\n\nFor more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).\n\n# Security / Disclosure\nIf you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/cloud-active-defense/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.\n\n# On the TODO list\nFeatures we plan to eventually release:\n  * [DONE] adding a configuration specifying where to find information about the user's session. We want to use this to add session / logged in user information in the alert.\n  * [DONE] show how to ingest alerts into fluentd for further processing (currently alerts are simply shown on the console)\n  * [DONE] show how to deploy into SAP Kyma as an extension of the mesh service\n\n# Code of Conduct\n\nWe as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.\n\n# Licensing\n\nCopyright 2024 SAP SE or an SAP affiliate company and cloud-active-defense contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/cloud-active-defense).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsap%2Fcloud-active-defense","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsap%2Fcloud-active-defense","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsap%2Fcloud-active-defense/lists"}