defender-serverless

Defender Serverless Plugin

Defender Serverless is a Serverless Framework plugin for automated resource management on Defender.

Installation

You can initialise your Serverless project directly using our pre-configured template:

sls install --url https://github.com/OpenZeppelin/defender-serverless/tree/main/template -n my-service

Alternatively, you can install it directly into an existing project with:

yarn install defender-serverless

Setup

This 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:

service: defender-serverless-template
configValidationMode: error
frameworkVersion: '3'

provider:
  name: defender
  stage: ${opt:stage, 'dev'}
  stackName: 'mystack'
  ssot: false

defender:
  key: '${env:TEAM_API_KEY}'
  secret: '${env:TEAM_API_SECRET}'

functions:
  autotask-example-1:
    name: 'Hello world from serverless'
    path: './autotasks/hello-world'
    relayer: ${self:resources.Resources.relayers.relayer-1}
    trigger:
      type: 'schedule'
      frequency: 1500
    paused: false

resources:
  Resources:
    policies:
      policy-1:
        gas-price-cap: 1000
        whitelist-receivers:
          - '0x0f06aB75c7DD497981b75CD82F6566e3a5CAd8f2'
        eip1559-pricing: true

    relayers:
      relayer-1:
        name: 'Test Relayer 1'
        network: 'rinkeby'
        min-balance: 1000
        policy: ${self:resources.Resources.policies.policy-1}
        api-keys:
          - key1

plugins:
  - defender-serverless

This 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.

Ensure the Defender Team API Keys are setup with all appropriate API capabilities.

The 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.

SSOT mode

Under 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. This 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.

Commands

Deploy

You can use sls deploy to deploy your current stack to Defender.

The deploy takes in an optional --stage flag, which is defaulted to dev when installed from the template above.

Moreover, the serverless.yml may contain an ssot property. More information can be found in the SSOT mode section.

This 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.

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.

Info

You 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.

Remove

You can use sls remove to remove all defender resources defined in the serverless.yml file.

To avoid potential loss of funds, Relayers can only be deleted from the Defender UI directly.

Logs

You can use sls logs --function <stack_resource_id> --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.

Invoke

You can use sls invoke --function <stack_resource_id> to manually run an autotask, given its identifier (e.g. mystack.autotask-example-1).

Each command has a standard output to a JSON object.

More information can be found on our documentation page here