{"id":29089625,"url":"https://github.com/openzeppelin/defender-serverless","last_synced_at":"2025-06-28T04:04:16.840Z","repository":{"id":59325819,"uuid":"533011944","full_name":"OpenZeppelin/defender-serverless","owner":"OpenZeppelin","description":"Configure a Defender environment via code","archived":false,"fork":false,"pushed_at":"2024-08-15T05:59:24.000Z","size":526,"stargazers_count":21,"open_issues_count":15,"forks_count":45,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-06-05T13:19:20.977Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenZeppelin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-09-05T18:15:17.000Z","updated_at":"2025-04-04T03:35:18.000Z","dependencies_parsed_at":"2024-05-09T15:10:54.081Z","dependency_job_id":"e8baa931-22b7-494f-8cbb-0fdf2e180cc1","html_url":"https://github.com/OpenZeppelin/defender-serverless","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/OpenZeppelin/defender-serverless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fdefender-serverless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fdefender-serverless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fdefender-serverless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fdefender-serverless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenZeppelin","download_url":"https://codeload.github.com/OpenZeppelin/defender-serverless/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fdefender-serverless/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262371684,"owners_count":23300595,"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":"2025-06-28T04:04:16.100Z","updated_at":"2025-06-28T04:04:16.827Z","avatar_url":"https://github.com/OpenZeppelin.png","language":"TypeScript","readme":"# Defender Serverless Plugin\n\nDefender Serverless is a Serverless Framework plugin for automated resource management on Defender.\n\n:warning: **This plugin is still under development. Bugs are expected. Use with care.**\n\n## Prerequisites\n\nServerless Framework: https://www.serverless.com/framework/docs/getting-started/\n\n## Installation\n\nYou can initialise your Serverless project directly using our pre-configured template:\n\n```\nsls install --url https://github.com/OpenZeppelin/defender-serverless/tree/main/template -n my-service\n```\n\nNote: for the command above to work correctly you need access to this repo.\n\nAlternatively, you can install it directly into an existing project with:\n\n`yarn add @openzeppelin/defender-serverless`\n\n## Setup\n\nThis plugin allows you to define Autotasks, Sentinels, Notifications, Relayers, Contracts, Policies and Secrets declaratively from a `serverless.yml` and provision them via the CLI using `serverless deploy`. An example template below with an autotask, a relayer, a policy and a single relayer API key defined:\n\n```yaml\nservice: defender-serverless-template\nconfigValidationMode: error\nframeworkVersion: '3'\n\nprovider:\n  name: defender\n  stage: ${opt:stage, 'dev'}\n  stackName: 'mystack'\n  ssot: false\n\ndefender:\n  key: '${env:TEAM_API_KEY}'\n  secret: '${env:TEAM_API_SECRET}'\n\nfunctions:\n  autotask-example-1:\n    name: 'Hello world from serverless'\n    path: './autotasks/hello-world'\n    relayer: ${self:resources.Resources.relayers.relayer-1}\n    trigger:\n      type: 'schedule'\n      frequency: 1500\n    paused: false\n\nresources:\n  Resources:\n    policies:\n      policy-1:\n        gas-price-cap: 1000\n        whitelist-receivers:\n          - '0x0f06aB75c7DD497981b75CD82F6566e3a5CAd8f2'\n        eip1559-pricing: true\n\n    relayers:\n      relayer-1:\n        name: 'Test Relayer 1'\n        network: 'sepolia'\n        min-balance: 1000\n        policy: ${self:resources.Resources.policies.policy-1}\n        api-keys:\n          - key1\n\nplugins:\n  - '@openzeppelin/defender-serverless'\n```\n\nThis requires setting the `key` and `secret` under the `defender` property of the YAML file. We recommend using environment variables or a secure (gitignored) configuration file to retrieve these values. Modify the `serverless.yml` accordingly.\n\nEnsure the Defender Team API Keys are setup with all appropriate API capabilities.\n\nThe `stackName` (e.g. mystack) is combined with the resource key (e.g. relayer-1) to uniquely identify each resource. This identifier is called the `stackResourceId` (e.g. mystack.relayer-1) and allows you to manage multiple deployments within the same Defender team.\n\n### SSOT mode\n\nUnder the `provider` property in the `serverless.yml` file, you can optionally add a `ssot` boolean. SSOT or Single Source of Truth, ensures that the state of your stack in Defender is perfectly in sync with the `serverless.yml` template.\nThis means that all Defender resources, that are not defined in your current template file, are removed from Defender, with the exception of Relayers, upon deployment. If SSOT is not defined in the template, it will default to `false`.\n\nAny resource removed from the `serverless.yml` file does _not_ get automatically deleted in order to prevent inadvertent resource deletion. For this behaviour to be anticipated, SSOT mode must be enabled.\n\n### Block Explorer Api Keys\n\nExported serverless configurations with Block Explorer Api Keys will not contain the `key` field but instead a `key-hash` field which is a keccak256 hash of the key. This must be replaced with the actual `key` field (and `key-hash` removed) before deploying\n\n### Secrets (Autotask)\n\nAutotask secrets can be defined both globally and per stack. Secrets defined under `global` are not affected by changes to the `stackName` and will retain when redeployed under a new stack. Secrets defined under `stack` will be removed (on the condition that [SSOT mode](#SSOT-mode) is enabled) when the stack is redeployed under a new `stackName`. To reference secrets defined under `stack`, use the following format: `\u003cstackname\u003e_\u003csecretkey\u003e`, for example `mystack_test`.\n\n```yaml\nsecrets:\n  # optional - global secrets are not affected by stackName changes\n  global:\n    foo: ${self:custom.config.secrets.foo}\n    hello: ${self:custom.config.secrets.hello}\n  # optional - stack secrets (formatted as \u003cstackname\u003e_\u003csecretkey\u003e)\n  stack:\n    test: ${self:custom.config.secrets.test}\n```\n\n### Types and Schema validation\n\nWe provide auto-generated documentation based on the JSON schemas:\n\n- [Defender Property](https://github.com/OpenZeppelin/defender-serverless/blob/main/src/types/docs/defender.md)\n- [Provider Property](https://github.com/OpenZeppelin/defender-serverless/blob/main/src/types/docs/provider.md)\n- [Function (Autotask) Property](https://github.com/OpenZeppelin/defender-serverless/blob/main/src/types/docs/function.md)\n- [Resources Property](https://github.com/OpenZeppelin/defender-serverless/blob/main/src/types/docs/resources.md)\n\nMore information on types can be found [here](https://github.com/OpenZeppelin/defender-serverless/blob/main/src/types/index.ts). Specifically, the types preceded with `Y` (e.g. YRelayer). For the schemas, you can check out the [docs-schema](https://github.com/OpenZeppelin/defender-serverless/blob/main/src/types/docs-schemas) folder.\n\nAdditionally, an [example project](https://github.com/OpenZeppelin/defender-serverless/blob/main/examples/defender-test-project/serverless.yml) is available which provides majority of properties that can be defined in the `serverless.yml` file.\n\n## Commands\n\n### Deploy\n\nYou can use `sls deploy` to deploy your current stack to Defender.\n\nThe deploy takes in an optional `--stage` flag, which is defaulted to `dev` when installed from the template above.\n\nMoreover, the `serverless.yml` may contain an `ssot` property. More information can be found in the [SSOT mode](#SSOT-mode) section.\n\nThis command will append a log entry in the `.defender` folder of the current working directory. Additionally, if any new relayer keys are created, these will be stored as JSON objects in the `.defender/relayer-keys` folder.\n\n\u003e When installed from the template, we ensure the `.defender` folder is ignored from any git commits. However, when installing directly, make sure to add this folder it your `.gitignore` file.\n\n### Info\n\nYou can use `sls info` to retrieve information on every resource defined in the `serverless.yml` file, including unique identifiers, and properties unique to each Defender component.\n\n### Remove\n\nYou can use `sls remove` to remove all defender resources defined in the `serverless.yml` file.\n\n\u003e To avoid potential loss of funds, Relayers can only be deleted from the Defender UI directly.\n\n### Logs\n\nYou can use `sls logs --function \u003cstack_resource_id\u003e --data {...}` to retrieve the latest autotask logs for a given autotask identifier (e.g. mystack.autotask-example-1). This command will run continiously and retrieve logs every 2 seconds. The `--data` flag is optional.\n\n### Invoke\n\nYou can use `sls invoke --function \u003cstack_resource_id\u003e` to manually run an autotask, given its identifier (e.g. mystack.autotask-example-1).\n\n\u003e Each command has a standard output to a JSON object.\n\nMore information can be found on our documentation page [here](https://docs.openzeppelin.com/defender/serverless-plugin.html)\n\n## Caveats\n\nNote that when setting up the notification configuration for a sentinel, the `channels` property will always be prioritised over `category`. A notification category can only be associated to a sentinel with no linked notification channels. This means that the `channels` property should be assigned the value `[]` in order to prioritise the `category` property.\n\n```yaml\nnotify-config:\n  channels: [] # assign channels as empty list if you wish to use a category\n  category: ${self:resources.Resources.categories.medium-severity} # optional\n```\n\nErrors thrown during the `deploy` process, will not revert any prior changes. Common errors are:\n\n- Not having set the API key and secret\n- Insufficient permissions for the API key\n- Validation error of the `serverless.yml` file (see [Types and Schema validation](#Types-and-Schema-validation))\n\nUsually, fixing the error and retrying the deploy should suffice as any existing resources will fall within the `update` clause of the deployment. However, if unsure, you can always call `sls remove` to remove the entire stack, and retry.\n\n## Publish a new release\n\n```bash\nnpm login\ngit checkout main\ngit pull origin main\n# increment version in package.json\nnpm publish\ngit add package.json\ngit commit -m 'v{version here}'\ngit push origin main\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fdefender-serverless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzeppelin%2Fdefender-serverless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fdefender-serverless/lists"}