honeyLambda turns a Lambda function into a trap that reports who walked into it

A honeytoken is a URL that only exists to be found

honeyLambda is a serverless application for creating and monitoring fake HTTP endpoints, which is to say URL honeytokens, on top of AWS Lambda and Amazon API Gateway.

The idea is simple enough to explain in one line and subtle enough to be worth a full deployment. A honeytoken is a credential-shaped artefact that is worthless on its own but whose use is a signal. The README describes placing these URL tokens in your inbox, in documents, in browser history, or embedding them as hidden links in your web pages. A separate project, honeybits, is suggested for spreading breadcrumbs across your systems so that an attacker who picks one up is led toward the traps.

The value of the approach is that it inverts the usual detection problem. Instead of trying to find out what a credential was used for, you find out that it was used at all, and often who used it. The README lists what this can surface: human attackers, malicious insiders, content scrapers, and bad bots.

The response side is equally part of the design. honeyLambda can notify you by Slack webhook, by email, and by SMS through Twilio, and the Slack alert includes a threat intelligence report for the source IP, done with the Cymon API v2. The alert screenshot in the repository is labelled with the threat intel image, so the source IP lookup is a visible part of the alert rather than a background enrichment.

The audience is a defender who can afford AWS costs and wants traps they can generate in bulk without a server to maintain.

The Serverless framework does the provisioning, which is why it is provider-shaped

honeyLambda is built on the Serverless framework, and that choice explains almost everything about how it is installed and what it can do.

The framework provisions the Lambda function and the API Gateway endpoint from a declarative service definition, so there is no infrastructure to build and no server to patch. The README lists the framework's own advantages as pay-what-you-use and provider agnostic, and the service definition lives in serverless.yml in the repository root.

The provider agnostic claim has a qualifier attached. The application can be deployed in AWS, Microsoft Azure, IBM OpenWhisk or Google Cloud, but only AWS was tested, and the main function may need small changes to support the others. The AWS path is the automatic one: on AWS, honeyLambda automatically creates the HTTP endpoints using Amazon API Gateway and then starts monitoring them with the honeyLambda Lambda function.

So the real deployment target is AWS, and the other providers are a portability gesture that has not been validated. That is worth knowing before you plan around it, since the deployment output shows a CloudFormation stack being created and uploaded, and API Gateway binary media type configuration is an AWS console step that has no equivalent in the other providers.

The repository layout is small and tells you where the logic lives. handler.py is the Lambda entry point, config.json holds the token and trap configuration, serverless.yml is the service definition, static/ holds the beacon image assets, template/ holds the response templates, and docs/ holds the images used in the README.

Setting the endpoint path, the config file, and the per-token response

Setup is a four-step sequence once the Serverless framework is installed.

First, install the framework globally with `npm install -g serverless`. Then fetch the application itself with `serverless install --url https://github.com/0x4d31/honeyLambda`, which pulls the service definition and the function code into a local directory.

Third, edit serverless.yml and set the HTTP endpoint path, with the default given as /v1/get-pass. This is the single most consequential line in the configuration, and the README does not say so. Every token you deploy lives under that one path, so a default path is a predictable path. Since the whole detection mechanism depends on a token being found by someone who should not find it, choosing a path nobody would guess is the difference between a trap and a public API.

Fourth, edit config.json and fill in your Slack Webhook URL, and change the trap and token configs as you need. The config file is also where the remote config option comes from: the TODO list marks loading config from Amazon S3 as done, so the same configuration can live in a bucket rather than in the deployment package.

The fifth capability worth calling out is per-token customisation. You can customise the HTTP response for each token, and the documented example is returning a 1x1 pixel beacon image, which you then embed the token in inside decoy documents or email as a tracking pixel. That turns the token from something that produces an alert when clicked into something that fires when the document is merely opened, which is a materially different detection capability.

The deploy output tells you what you actually created

Deployment is a single command, `serverless deploy`, after AWS credentials are set up. The output is worth reading closely, because it is the record of what now exists in your account.

Serverless: Packaging service...
Serverless: Creating Stack...
Serverless: Checking Stack create progress...
.....
Serverless: Stack create finished...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Uploading service .zip file to S3 (116.22 KB)...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
.................................
Serverless: Stack update finished...
Service Information
service: honeyLambda
stage: dev
region: ap-southeast-2
api keys:
  None
endpoints:
  GET - https://rz1bEXAMPLE.execute-api.ap-southeast-2.amazonaws.com/dev/v1/get-pass
functions:
  honeylambda: honeyLambda-dev-honeylambda

Three things stand out. The deployment is a CloudFormation stack, so the resources are managed by the framework and can be torn down with it. The stage is dev by default, and the stage name is part of the endpoint URL, which means the dev stage is publicly routable on the internet the moment you deploy it. And the endpoint is a plain GET on a public execute-api hostname with no api keys, which is correct for this use case and also means the endpoint is trivially discoverable by anyone scanning for API Gateway hostnames.

The service zip is 116.22 KB, which is the whole deployed function. A honeytoken deployment is cheap in both senses.

After deploying, the README's usage step is simply to open the generated URL in your browser to test that it works, and the screenshot of the HTTP response in the repository shows the configured response coming back.

Binary responses need a manual API Gateway step that serverless cannot do for you

There is one deployment step that will bite you if you plan to use the beacon image, and the README is explicit about it.

If you want to return binary in the HTTP response, for example with a Content-Type of image/png, you have to manually configure Binary Support using the Amazon API Gateway console, because it is not yet possible to set binary media types automatically using serverless. The instruction is to open the console, add the binary media type /*/*, and save. Once done, you have to re-deploy the API to the dev stage.

That is an awkwardness in the design rather than a documentation gap. A response that is a pixel image is the mechanism behind the tracking pixel capability, and it is the capability that makes the tool work as a beacon rather than as a click trap. The dependency on a console click plus a re-deploy means that capability is not available in a clean automated pipeline without someone doing the manual step first, and it means an operator who skips it gets a broken image rather than an error.

The re-deploy instruction is also specific to the dev stage, which suggests the workflow assumes you are iterating on the dev stage. The same endpoint path is shared by the stages, so the dev-stage re-deploy is what propagates the binary media type change.

Where honeyLambda is the wrong tool

The clearest wrong-tool case is a need for per-token attribution. The configuration model described in the README is a set of tokens under a single endpoint path, and the endpoint is a single GET route. If your requirement is to tell which of fifty leaked documents was opened, or to attribute a specific token to a specific customer, the design has to be extended, and the README does not describe a scheme for it. The TODO list adds HTTP Client Fingerprinting to the todo column, which tells you the analysis side of the tool is still thin, and that the current signal is the source IP.

The second case is a requirement for a commercial threat intelligence feed. The source IP lookup is done with the Cymon API v2, and that is a single named provider in the configuration. If your process depends on a specific feed with its own coverage and licensing, you are tied to that choice.

The third case is a deployment model that is not the Serverless framework. Despite the provider agnostic claim, the whole install path, the binary media type step and the CloudFormation output are tied to that toolchain.

The alternative approach is worth naming precisely. A managed deception platform, where a service hosts a large pool of honeytoken endpoints for you and gives you per-token dashboards and a web interface for generating tokens, removes the deployment work entirely and adds per-token identity, which is the thing honeyLambda leaves you to build. The difference in approach is that honeyLambda gives you a small, readable Python function and a declarative service definition you can audit, modify and version, with alerts going to channels you already own, while a managed platform gives you a larger feature set and a dependency on somebody else's infrastructure. If you need the token generator to be a small artifact in your own repository that a platform team can review, honeyLambda is the closer fit. If you need a working deception capability this week without anyone touching AWS, it is not.

A GPL-3.0 project with no releases and a last push in September 2026

Two facts about the project's state are worth stating plainly for anyone putting it into a security stack.

First, there are no GitHub releases. The repository has no version tags to point at, so there is no published upgrade path and no changelog to consult. What you deploy is what is in the master branch at the time you run serverless install. The last push to the repository was on 2026-09-18, and the default branch is master.

Second, the licence is GPL-3.0, with the badge in the README and a LICENSE file in the tree. For a tool you deploy into your own AWS account rather than distribute, the practical effect of the copyleft is limited, but if you intend to modify the Lambda function and hand the modified version to another team or to a reseller, that is a case to read the licence text about rather than assume.

The completed items in the TODO list are more informative than the outstanding ones, because they map to the feature set: remote config from Amazon S3, returning a beacon image as the HTTP response, customising the HTTP response per token, checking the source IP against threat intelligence feeds such as the Cymon API, email alert, and SMS alert through Twilio. The single open item is HTTP Client Fingerprinting.

That fingerprinting gap is the honest limitation of the current design. Right now, a hit tells you an address made a request. It does not tell you whether the request came from a browser, a scanner or a script, which is exactly the signal that separates a curious visitor from a scheduled scraper. Until that is done, expect to triage alerts by hand.

Editorial conclusion

honeyLambda suits a defender who wants cheap, self-service traps that can be scattered through documents, inboxes and web pages, and who will accept a fixed URL path per deployment. It does not suit a team that needs per-user or per-campaign token attribution, a commercial threat intelligence feed, or a deployment model that is not Serverless framework based. Before adopting, set the endpoint path in serverless.yml away from the default /v1/get-pass, confirm the Cymon API v2 lookup still works for your region, and read the binary media type step carefully, because returning a beacon image needs a manual API Gateway configuration that serverless cannot yet set for you.

Frequently asked questions

Official sources

1. 0x4D31/honeyLambda on GitHub
2. Issues
3. License: GPL-3.0
4. README