Providers

AWS Appsync (declared as appsync): currently can only rotate secrets. Returns rotated keys in the format:

   {
      "provider": "aws_appsync",
      "key": "key",
      "secret": "secret"
   }

Uses client AWS AppSync.

AWS IAM (declared as iam): can only rotate secrets (as it doesn’t really make sense for it to receive (via distribution) any secrets). Returns rotated keys in the format:

   {
      "provider": "iam",
      "key": "<AWS ACCESS KEY ID>",
      "secret": "<AWS ACCESS SECRET KEY>"
   }

Uses client AWS IAM.

AWS Kinesis Firehose (declared as firehose): can only distribute secrets to Firehose destinations. It doesn’t make sense for it to rotate! The distribute spec looks like this:

    distribute:
    -
        key: streamname
        provider: firehose
        source: secret_key
        config:
            dest_type: splunk | http
            region: AWS Region
        envs:
            - dev

This will distribute a secret to a Firehose delivery stream destination of type dest_type, for a stream name of key.

Valid values for dest_type are ‘splunk’ or ‘http’, corresponding to those options supported by AWS (https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html). The provider will take the key from the secret specified by source, and save it to the token or password of the Firehose destination.

Region is an optional value and can be used to specify which AWS region the stream lives in - if omitted Keydra will just use the region it is running in.

As an example, the Firehose Splunk destination sends events to a Splunk HTTP Event Collector (HEC), so the following would rotate a HEC token nightly, and save the value to a Firehose stream located in region us-east-1:

   sample:
      key: keydra_managed_sample
      description: Example
      custodians: my_team
      provider: splunk_hec
      rotate: nightly
      config:
         host: my.splunkhost
         rotatewith:
            key: keydra/splunk/admin
            provider: secretsmanager
      distribute:
      -
         key: streamname
         provider: firehose
         source: hecToken
         config:
            dest_type: splunk
            region: us-east-1
         envs:
            - dev

Uses client AWS Kinesis Firehose.

AWS SecretsManager (declared as secretsmanager): can distribute and/or rotate secrets.

If rotateing, a config section must be provided, with either bypass: true (pretend to rotate, but don’t really - just fetch the current password from the param) or rotate_attribute: key (specify the key in the JSON secret which holds the actual password value to rotate).

Optionally, the config section can specify one or more of the following to control how new passwords are generated.

• length: int (32)
• exclude_char: str (’’)
• exclude_num: bool (False)
• exclude_punct: bool (False)
• exclude_upper: bool (False)
• exclude_lower: bool (False)
• include_space: bool (False)
• require_each_type: bool (True)

secretsmanager is greedy in other words, it will take all that is provided by the secret and stick it into AWS SecretsManager. So no 1-1 mapping or cherry picking fragments.

Uses client AWS Secrets Manager.

AWS SSM Parameter Store (declared as ssmparameterstore): can distribute and/or rotate secrets. It exclusively uses SecureStrings to protect secrets, and currently only supports encryption using the default AWS Managed Key for Parameter Store.

If rotateing, a config section must be provided, with either bypass: true (pretend to rotate, but don’t really - just fetch the current password from the param) or rotate_attribute: key (specify the key in the JSON secret which holds the actual password value to rotate)

Optionally, the config section can specify how new passwords are generated.

Like secretsmanager, ssmparameterstore is greedy, and the config section can optionally specify how new passwords are generated. See above Secrets Manager section for details.

Uses client AWS SSM Parameter Store.

Bitbucket (declared as bitbucket): can distribute secrets to the following scopes:

• account (account-level env variables)
• repository (build-level or development-level env variables)
• deployment (deployment environment env variable)

In the future will also support rotate keys as its own secrets should be rotated by Keydra.

It is also a config provider. See About Config Providers.

bitbucket requires 1:1 mapping of the secret, this is done via source.

Uses client Bitbucket.

Cloudflare (declared as cloudflare): can rotate secrets. Requires a token with the Can create tokens permission in Cloudflare, registered under manage_tokens.secret in SecretsManager. When invoked rotates all of the tokens pertaining to that account and make their ID and SECRET available, as per <token_name>.key and <token_name>.secret.

Uses client Cloudflare.

Uses client Contentful.

Github can distribute secrets to the repository scope only. It is also a config provider. See About Config Providers), and can be used as a source for your secret and environment specs. In your SAM template, use KEYDRA_CFG_PROVIDER=github to tell Keydra to look in Github for secrets to manage.

This provider is really just an MVP to kickstart Github support, so other secret scopes have not yet been implemented.

For a given secret specification, the distribute function will add an encrypted secret to the specified repository. See https://docs.github.com/en/actions/reference/encrypted-secrets.

For example, for a secret spec of:

   sample:
      key: keydra_managed_sample
      description: A example secret which exists in IAM
      custodians: my_team
      provider: IAM
      rotate: nightly
      distribute:
      - config:
            repository: keydraconfiguration
            account_username: me
            scope: repository
         envs:
            - dev
         key: AWS_ACCESS_KEY_ID
         provider: github
         source: key
      - config:
            repository: keydraconfiguration
            account_username: me
            scope: repository
         envs:
            - dev
         key: AWS_SECRET_ACCESS_KEY
         provider: github
         source: secret

The provider will take the AWS IAM user credentials and, using an access token from the AWS Secrets Manager secret located at keydra/github, encrypt the IAM user Id/password values and save them to secrets within the keydraconfiguration repo of the me organisation or Github account.

To use Github as your main Keydra source provider, set the relevant environment variables that your Lambda runs as. As in, set the following in your SAM template.yaml:

   Variables:
      KEYDRA_CFG_PROVIDER: github
      KEYDRA_CFG_CONFIG_ACCOUNTUSERNAME: myAccountName
      KEYDRA_CFG_CONFIG_SECRETS_REPOSITORY: keydraconfiguration
      KEYDRA_CFG_CONFIG_SECRETS_PATH: main/config/secrets.yaml
      KEYDRA_CFG_CONFIG_SECRETS_FILETYPE: yaml
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_REPOSITORY: keydraconfiguration
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_PATH: main/config/environments.yaml
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_FILETYPE: yaml

Uses client Github.

Gitlab can distribute secrets to the repository scope only. It is also a config provider (see About Config Providers), and can be used as a source for your secret and environment specs. In your SAM template, use KEYDRA_CFG_PROVIDER=gitlab to tell Keydra to look in Gitlab for secrets to manage.

This provider has functionality similar to the Github provider (see above).

For a given secret specification, the distribute function will add a repository (CI/CD) variable to the specified repository. See https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project.

For example, for a secret spec of:

   sample:
      key: keydra_managed_sample
      description: A example secret which exists in IAM
      custodians: my_team
      provider: IAM
      rotate: nightly
      distribute:
      - config:
            repository: keydraconfiguration
            scope: repository
         envs:
            - dev
         key: AWS_ACCESS_KEY_ID
         provider: gitlab
         source: key
      - config:
            repository: keydraconfiguration
            scope: repository
         envs:
            - dev
         key: AWS_SECRET_ACCESS_KEY
         provider: gitlab
         source: secret

The provider will take the AWS IAM user credentials and, using an access token from the AWS Secrets Manager secret located at keydra/gitlab, encrypt the IAM user Id/password values and save them to secrets within the keydraconfiguration repo.

To use Gitlab as your main Keydra source provider, set the relevant environment variables that your Lambda runs as. As in, set the following in your SAM template.yaml:

   Variables:
      KEYDRA_CFG_PROVIDER: gitlab
      KEYDRA_CFG_CONFIG_SECRETS_REPOSITORY: keydraconfiguration
      KEYDRA_CFG_CONFIG_SECRETS_REPOSITORYBRANCH: main
      KEYDRA_CFG_CONFIG_SECRETS_PATH: config/secrets.yaml
      KEYDRA_CFG_CONFIG_SECRETS_FILETYPE: yaml
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_REPOSITORY: keydraconfiguration
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_REPOSITORYBRANCH: main
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_PATH: config/environments.yaml
      KEYDRA_CFG_CONFIG_ENVIRONMENTS_FILETYPE: yaml
      KEYDRA_CFG_CONFIG_ACCOUNTUSERNAME: notRequired

Uses client Gitlab.

Provides password rotation support for Qualys accounts. Only rotate has been implemented, distribution is not (yet?) supported.

For a given secret specification, the rotate function fetches the contents of a AWS Secrets Manager secret located at keydra/qualys/<key> (using the key from the spec), and changes the password of the user specified on the Qualys platform. As Qualys does not permit a user to change their own password via API, the secret spec needs to specify a second account to be used to make the change.

For example, for a secret spec of:

    sample:
      description: API User
      key: api
      provider: qualys
      rotate: nightly
      config:
         rotatewith:
            key: keydra/qualys/backup
            provider: secretsmanager
      distribute:
      -
         key: keydra/qualys/api
         provider: secretsmanager
         source: secret
         envs:
            - prod

The provider will take an AWS Secrets Manager secret, located at keydra/qualys/api:

   {
      "platform": "US3",
      "username": "apiuser",
      "password": "Ssh.Secret!"
   }

Then use the creds of the secret at keydra/qualys/backup (in Secrets Manager, as configured in the spec) to connect to the Qualys API and change the password of the apiuser account. With the distribution setup in the example, the new password will then be placed into Secrets Manager, replacing the password with the new one.

See https://www.qualys.com/platform-identification/ to identify which platform your instance is on.

Uses client Qualys.

Salesforce (declared as salesforce): currently can only rotate secrets. Please note that users need to be manually created in salesforce before added here.

Sample secret spec:

   key: salesforce_sample
   description: Salesforce Example
   custodians: your_team
   provider: salesforce
   rotate: nightly
   distribute:
   -
      key: keydra/salesforce/salesforce_sample
      provider: secretsmanager
      source: secret
      envs:
         - prod

The Secrets Manager entry format is as follows:

   {
   "provider": "salesforce",
   "key": "my_sf_user",
   "secret": "my_sf_password",
   "token": "sf_token",
   "domain": "sf_domain"
   }

The field names can be customised via a config section in the spec, e.g.:

   key: salesforce_sample
   description: Salesforce Example
   provider: salesforce
   config:
      user_field: SF_USERNAME
      password_field: SF_PASSWORD
      token_field: SF_TOKEN
      domain_field: SF_DOMAIN
   # ...

Uses client Salesforce.

Salesforce Marketing Cloud (declared as salesforce_marketing_cloud): currently can only rotate secrets. Please note that users need to be manually created in salesforce before added here, and be setup with the following roles:

• Administration
  • Users - Update (Allow)
• Email
  • Admin
    • API Access
      • WebService API (Allow)
      • XML API (Allow)

Sample secret spec:

    salesforce_marketing_cloud_user:
        key: sfuser-dev
        description: Secret for break glass access to Salesforce Dev
        custodians: sf_team
        provider: salesforce_marketing_cloud
        rotate: nightly
        distribute:
        -
            key: keydra/salesforce/sfmc-user
            provider: secretsmanager
            source: secret
            envs:
                - dev

The Secrets Manager entry format is as follows:

   {
   "provider": "salesforce_marketing_cloud",
   "SF_USERNAME": "my_sf_user",
   "SF_PASSWORD": "my_sf_password",
   "mid": "sfmc_instance_mid",
   "businessUnit": "sfmc_instance_bu_id",
   "subdomain": "sfmc_subdomain",
   }

The field names can be customised via a config section in the spec, e.g.:

   key: salesforce_marketing_cloud sample
   description: Salesforce Marketing Cloud Example
   provider: salesforce_marketing_cloud
   config:
      user_field: SF_USERNAME,
      password_field: SF_PASSWORD,
      subdomain_field: SF_SUBDOMAIN,
      businessUnit_field: SF_BUSINESUNIT,
      mid_field: SF_MID
      
   # ...

Uses client Salesforce Marketing Cloud.

Provides password (and token!) rotation and distribution support for Splunk. Rotation allows for Splunk account passwords/tokens to be rotated, while Distribute allows you to save passwords from other providers in Splunk apps, like Qualys or AWS.

Rotation can be done on only one Splunk instance at a time.

When rotating passwords, a new 32 character password is generated (using AWS Secrets Manager) and the provider changes the Splunk password for the account corresponding to the “key” value in the secret. This change is made on the Splunk host defined within the “config” section of the secret.

For Splunk Tokens, the current token for that user is used to create a new token, and delete the old. No additional configuration is required - the provider auto detects the type of “password” being rotated, and acts accordingly.

An example secret spec to rotate a Splunk user password and store in AWS Secrets Manager:

   key: splunkuser
   description: Splunk Rotation Example
   custodians: your_team
   provider: splunk
   rotate: nightly
   config:
      host: your.splunkhostname.com
   distribute:
   -
      key: keydra/splunk/splunkuser
      provider: secretsmanager
      source: secret
      envs:
         - prod

The Secrets Manager entry format is as follows:

   {
   "username": "splunkuser",
   "password": "abcdefghijklmnopqrstuvwxyz1234567890"
   }

Distribution is a little more complex; configuring a Splunk App or Add-On with a service account to be used by that app to connect to various data sources. Only one destination host can be specified; if you need to send to more Splunk hosts you will need another distribution entry. The provider supports either Splunk storage passwords or a more custom method of actually storing the password on Splunk - which one to use depends on the destination Splunk TA/app. For example, the AWS app for Splunk uses the custom method, while the Qualys app uses storage passwords.

The destination app must already be installed on the Splunk instance, though the config entry / storage password will be created if it doesn’t already exist.

In the config section:

An example, to rotate an IAM user and distribute it into the AWS app/TA of a Splunk instance:

   key: km_managed_splunk
   description: Rotate an AWS Splunk integration account
   custodians: your_team
   provider: IAM
   rotate: nightly
   distribute:
   -
      key: aws_security
      provider: splunk
      provider_secret_key: provisioning_user
      source:
         key_id: key
         secret_key: secret
      config:
         app: Splunk_TA_aws
         appconfig:
           category: 1
           output_mode: json
         host: your.splunkhostname.com
         path: splunk_ta_aws_aws_account
      envs:
         - prod

What does this do? Keydra will rotate these IAM credentials, then use the Splunk credentials stored in an AWS Secrets Manager secret, located at ‘keydra/splunk/provisioning_user’ to connect to Splunk. It will then post the key value pairs in the config/appconfig section to the app specified (Splunk_TA_aws), mixing in the keys in the source section after mapping them from the secret. As in, the key value from the IAM secret will be posted as key_id.

Note: The category 1 reference? This is the category of the account. ‘1’ is AWS Global (not GovCloud).

If your app uses storage passwords (like the Qualys app), the distribution stanza would look more like:

   -
   provider: splunk
   provider_secret_key: provisioning_user
   source:
      name: username
      password: password
   config:
      app: TA-QualysCloudPlatform
      appconfig:
         output_mode: json
      host: your.splunkhostname.com
   envs:
      - prod

Uses client Splunk.

Provides rotation support for Splunk Http Event Collector (HEC) tokens. Distribution is not supported by this provider.

Like the Qualys provider, the spec requires you to specify a rotatewith value, which is where Keydra can find creds with which to access Splunk and make the change.

Both Splunk Enterprise and Splunk Cloud are supported, but only the ‘Classic’ experience for the latter. If using with Splunk Cloud, make sure the Splunk user you are rotating with has a role with the dmc_deploy_token_http and list_token_http capabilities.

An additional note on Splunk Cloud, which uses a DMC to distribute content to the indexes; rotating HEC tokens can take up to 5 minutes due to the cluster synchoronisation requirements.

   key: hec1
   description: Splunk HEC Rotation Example
   custodians: your_team
   provider: splunk_hec
   rotate: nightly
   config:
      host: your.splunkhostname.com
      rotatewith:
         key: keydra/splunk/admin
         provider: secretsmanager
   distribute:
   -
      key: keydra/splunk/hec1
      provider: secretsmanager
      source: secret
      envs:
         - prod

The Secrets Manager entry format is as follows:

   {
   "hecInputName": "HEC Input Name",
   "hecToken": "13e58a8a-ab69-4c89-8941-51b26d797e5a"
   }

Uses client Splunk.