{"id":31551445,"url":"https://github.com/slappforge/nodejs-lambda-debugger","last_synced_at":"2025-10-30T04:17:08.473Z","repository":{"id":36467725,"uuid":"225608362","full_name":"slappforge/nodejs-lambda-debugger","owner":"slappforge","description":"SLAppForge Debugger for NodeJS is a toolkit that can be utilized to perform step-through debugging for the Lambda functions executing on live AWS environment, using your own local IDE.","archived":false,"fork":false,"pushed_at":"2022-03-25T21:05:17.000Z","size":102,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-21T01:30:54.295Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.slappforge.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slappforge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-03T11:55:28.000Z","updated_at":"2020-10-16T10:59:03.000Z","dependencies_parsed_at":"2022-08-08T15:01:19.328Z","dependency_job_id":null,"html_url":"https://github.com/slappforge/nodejs-lambda-debugger","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/slappforge/nodejs-lambda-debugger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slappforge%2Fnodejs-lambda-debugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slappforge%2Fnodejs-lambda-debugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slappforge%2Fnodejs-lambda-debugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slappforge%2Fnodejs-lambda-debugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slappforge","download_url":"https://codeload.github.com/slappforge/nodejs-lambda-debugger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slappforge%2Fnodejs-lambda-debugger/sbom","scorecard":{"id":831030,"data":{"date":"2025-08-11","repo":{"name":"github.com/slappforge/nodejs-lambda-debugger","commit":"1c54d461da69fca1b86033bb3f0e633c5de0f13c"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.6,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: containerImage not pinned by hash: broker/Dockerfile:1: pin your Docker image by updating node:8-alpine to node:8-alpine@sha256:38f7bf07ffd72ac612ec8c829cb20ad416518dbb679768d7733c93175453f4d4","Warn: npmCommand not pinned by hash: broker/Dockerfile:9","Warn: npmCommand not pinned by hash: layer/build.sh:5","Info:   0 out of   1 containerImage dependencies pinned","Info:   0 out of   2 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":0,"reason":"11 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-4w2v-q235-vp99","Warn: Project is vulnerable to: GHSA-cph5-m8f7-6c5x","Warn: Project is vulnerable to: GHSA-wf5p-g6vw-rhxx","Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6","Warn: Project is vulnerable to: GHSA-74fj-2j2h-c42q","Warn: Project is vulnerable to: GHSA-pw2r-vq6v-hr8c","Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc","Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q","Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m","Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-23T17:48:56.692Z","repository_id":36467725,"created_at":"2025-08-23T17:48:56.692Z","updated_at":"2025-08-23T17:48:56.692Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278358487,"owners_count":25973949,"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","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-10-04T18:56:21.261Z","updated_at":"2025-10-04T18:56:24.237Z","avatar_url":"https://github.com/slappforge.png","language":"JavaScript","readme":"\n\u003cdiv style=\"text-align:center\"\u003e\n    \u003cimg src=\"https://s3.amazonaws.com/resources.sigma.slappforge.com/slappforge_logo_color.png\" alt=\"SLAppForge\" width=\"300\"/\u003e\n\u003c/div\u003e\n\n# **SLAppForge Debugger for NodeJS**\n\nSLAppForge Debugger for NodeJS is a toolkit that can be utilized to perform step-through debugging for the **Lambda \nfunctions executing on live AWS environment**, using your own local IDE. \n\n## How it works?\n\nThis toolkit contains 3 components as below.\n\n* Lambda Proxy\n* Local Client\n* Broker Server\n\n#### Lambda Proxy\n\nThis is a NPM package that should be added as a dependency to the lambda project. Once added it acts as a wrapper for \nthe actual lambda code by reaching up into the parent and swap the specified lambda handler with its own handler before \nthe lambda code is executed. Then the proxy code takes over and launches the actual handler in as a child process.\n\nThen this Lambda Proxy acts as the intermediary that exchanges V8 protocol messages between the lambda process and the\nremote broker server.\n\n#### Local Client\n\nThis is a NPM command line tool that should be installed as a global package in the developer machine. Once invoked with\nthe required parameters, it acts as the intermediary that exchanges V8 protocol messages between the IDE debugger and the\nremote broker server.\n\n#### Broker Server\n\nThis is basically a WebSocket based server running on a publicly accessible IP. Both Lambda Proxy and the Local Client\nconnect to this server and the server acts as the intermediary that exchanges V8 protocol messages between them.\n\nIn summary, Lambda Proxy, Broker Server and the Local Client connect together to create a WebSocket channel between the\nLambda running on AWS and the IDE debugger on your local machine.\n\n## How to use?\n\n### Prerequisites\n\nAs a prerequisite for using this toolkit, you should obtain an access key pair from the SLAppForge Access Key Manager.\nFor that, please visit https://www.slappforge.com/java-debug and login with your \n[SLAppForge Sigma](https://sigma.slappforge.com/) account. If you don't have a Sigma account you can create one for free\nfrom [here](https://sigma.slappforge.com/#/signup). Once logged in, you can generate an **Access Key** and an **Access \nSecret**.\n\n### Configuration\n\n#### Adding Proxy to the Lambda function\n\nTo use this toolkit, the proxy component should be added to your NodeJS Lambda function. For that you have 2 alternatives.\n\n**Option 1**\n\nAdd `slappforge-lambda-debug-proxy` as a NPM dependency to your Lambda function.\n```\nnpm i slappforge-lambda-debug-proxy --save\n```\n\n**Option 2**\n\nAdd the Lambda Layer with the following ARN to your Lambda function.\n```\narn:aws:lambda:us-east-1:892904900711:layer:slappforge-debug-nodejs-1-0-0-build-01:1\n```\n\nAfter adding the proxy component as a dependency using one of the options, require the package at the very end of the \nfile that contains the Lambda handler that you want to debug.\n\nAlso make sure to set a reasonable **Timeout** value for the Lambda function, so that you have enough time for debugging,\nbefore the Lambda function runs out of time.\n\n```\nexports.handler = async (event) =\u003e {\n    console.log(event);\n    return 'Hello World!'; \n};\n\nrequire('slappforge-lambda-debug-proxy');\n```\n\n\u003e **Important**\n\u003e\n\u003e If you intend to use **Visual Studio Code** as the IDE for the debugging, please add a `debugger;` statement as the \n\u003e very first line of the function handler.\n\u003e ```\n\u003e exports.handler = async (event) =\u003e {\n\u003e   debugger;\n\u003e   // rest of the function code\n\u003e };\n\u003e \n\u003e require('slappforge-lambda-debug-proxy');\n\u003e ```\n\n#### Configuring Lambda environment variables\n\nThen the following environment variables must be set for the Lambda function with the appropriate values.\n\n| Name | Required | Description  |\n|------|:--------:| -------------|\n|`SLAPP_DEBUGGER_ACTIVE` |:white_check_mark: | This is the flag that indicates whether the Lambda should be invoked in debug mode or not. Setting this to `true` will enable debugging.\n|`SLAPP_KEY` |:white_check_mark: | This is the Access Key obtained from the access key manager\n|`SLAPP_SECRET` |:white_check_mark: | This is the Access Secret obtained from the access key manager\n|`SLAPP_SESSION` |:white_check_mark: | This is a unique ID to distinguish this Lambda function for debugger to connect. This can be any string value.\n\nIn addition to the above, following optional environment variables can be used to provide the Broker Server details.\n\n| Name | Required | Description  |\n|------|:--------:| -------------|\n|`SLAPP_DEBUG_BROKER_HOST` |:x: | This is the host name or the IP address of the Broker server. Default value is `lambda-debug.slappforge.com`\n|`SLAPP_DEBUG_BROKER_PORT` |:x: | This is the lambda facing port of the Broker server. Default value is `8181`\n\n#### Installing and running the Local Client\n\nThe Local Client module of the toolkit should be installed as a global NPM dependency on the developer machine.\n```\nnpm i slappforge-debug-client -g\n```\n\nThen it should be invoked via a terminal providing the following arguments.\n\n| Short Argument | Long Argument | Required | Description  |\n|:---------:|---------|:----------:| -------------|\n|`-f` | `--session` |:white_check_mark: | This is a unique ID set as the `SLAPP_SESSION` variable of the Lambda function\n|`-k` |`--key` |:white_check_mark: | This is the Access Key obtained from the access key manager\n|`-x` |`--secret` |:white_check_mark: | This is the Access Secret obtained from the access key manager\n|`-s` |`--server` |:x: | This is the host name or the IP address of the Broker server. Default value is `lambda-debug.slappforge.com`\n|`-p` |`--port` |:x: | This is the debugger facing port of the Broker server. Default value is `9239`\n|`-v` |`--verbose` |:x: | Flag to enable verbose logging for the client\n                                                           \n```\nslp-debug-client -f=MyFunction -k=abcd=efgh-1234-5678 -x=abc123def456ghi789\n```\n\n#### Configuring the IDE Debugger\n\nConfiguring steps for the IDE debugger varies based on the IDE in use. This toolkit has been currently tested with \nJetbrains IntelliJ IDEA, Jetbrains WebStorm and VS Code IDEs. It might work with other IDEs that generally support NodeJS \nremote debugging.\n\n**IntelliJ IDEA / WebStorm**\n\n* Open the project containing the Lambda source code and create a new **Run/Debug Configuration** selecting **Attach to \nNodeJS/Chrome** as the type from left side panel\n* Provide any name for the Run/Debug profile\n* Configure the **Host** as `localhost` and the **Port** as `9249`\n* Select the **Attach to** type as `Chrome or NodeJS \u003e 6.3 started with --inspect`\n* Click **Apply** and then **OK**\n\n**VS Code**\n\n* Open the workspace containing the Lambda source code and add a new launch configuration similar to below. You can\nprovide any name for the `name` field.\n```\n{\n    \"type\": \"node\",\n    \"request\": \"attach\",\n    \"name\": \"Attach to Remote Lambda\",\n    \"address\": \"127.0.0.1\",\n    \"port\": 9249,\n    \"localRoot\": \"${workspaceFolder}\",\n    \"remoteRoot\": \"/var/task\",\n    \"outFiles\": [\n        \"${workspaceFolder}/**/*.js\"\n    ]\n}\n```\n* If your Lambda source code is in a sub directory of the current workspace, you have to append that sub path to the \n`localRoot` field.\n```\n\"localRoot\": \"${workspaceFolder}/subPath\"\n```\n\n* Similarly, if your Lambda deployment bundle has an enclosing directory, you have to append that also to the \n`remoteRoot` field.\n```\n\"remoteRoot\": \"/var/task/MyLambda\"\n```\n\n* Finally save the `launch.json` file\n\n### Running the Debugger \n\n* First start the **Local Client** providing the necessary parameters as mentioned [here](#Installing-and-running-the-Local-Client)\n* Then invoke the Lambda with debugging enabled. You can do this either using the Test functionality on the AWS Lambda\nconsole, or by triggering an actual event such as API Gateway request, S3 operation, etc.\n* Then the Lambda execution will suspend waiting for a debugger to connect\n* Finally invoke the Debugger from the IDE and wait for a couple of seconds for it to connect through. Make sure to add \nat least one debug breakpoint **before** you invoke the IDE debugger, so that the Lambda execution will suspend at that \npoint.\n* Happy Debugging!\n---\n\nThis toolkit is developed based on the [Trek10 AWS Lambda Debugger](https://github.com/trek10inc/aws-lambda-debugger), \nKudos to [Rob Ribeiro](https://github.com/azurelogic) and [Trek10](https://www.trek10.com/) for the awesome work :pray:.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslappforge%2Fnodejs-lambda-debugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslappforge%2Fnodejs-lambda-debugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslappforge%2Fnodejs-lambda-debugger/lists"}