Getting Started with DevOps Secrets Safe

Before proceeding with this section, please ensure a new instance of DevOps Secrets Safe (DSS) is running and that the DSS Command Line Interface (CLI) is configured to communicate with it.

For more information about how to configure the DevOps Secrets Safe CLI, please see Install the DevOps Secrets Safe CLI.

Initialize DevOps Secrets Safe

  1. Initialize DevOps Secrets Safe

    $ ssrun init

    Set the desired password for the root user account in the DSS instance when prompted. The password must be at least 10 characters long. A successful call to initialize returns the master key for this DSS instance. Save this key to a file.

The remainder of this guide assumes that the root account password for the DevOps Secrets Safe instance has been set to rootpassword and that the master key has been saved to a file called master.txt.

  1. Unseal DevOps Secrets Safe

    $ ssrun unseal -f master.txt

    All CLI commands aside from Initialize and Unseal will be unavailable until the instance is unsealed. This command will put the Secrets Safe application into a state where secrets may be saved and retrieved.

  2. Log in to DevOps Secrets Safe as root

    $ ssrun login -u root -p rootpassword

Manage Users

Before starting this section, ensure you have initialized, unsealed, and logged into DevOps Secrets Safe as root.

For more information about how to initialize DSS, please see Initialize DevOps Secrets Safe.

  1. Create a new user

    $ ssrun user create -u NewUser -p NewUserPassword

Passwords must be 10 characters in length.

  1. View the list of users

    $ ssrun user get -v

The principal discovery mechanism accepts any subset of the URI {identity_provider}/{principal_type}/{principal_name}/{principal_extension_data}. Therefore, the URI above will return all internal users. Additionally, the (optional) -v flag can be used to get a full listing of principals or principal containers attributes. Otherwise, a slim view of each principal or principal container is returned.

  1. Create a secret

    $ echo -n "I love my test content" | ssrun secret create testsecret:mytestsecret

    Whenever you reference a secret, the URI must be in the format {scopePath}:{secretName}. For example, path/to/secrets:secretName.

The echo line may only be performed in bash and similar shells.

For more information on managing secrets, please see Manage Secrets and Scopes.

  1. Authorize the new user to read the secret

    The create-authorization command accepts the following arguments:

    $ ssrun authorization create -p principal/internal/user/NewUser -o read -a allow secret/testsecret:mytestsecret
    • -p (Required) URI of the principal the access control is being applied to.
      • A users URI can be derived using the principal discovery mechanism detailed in step 2.
    • -o (Optional) Operations authorization applies to.
      • Options are create|read|update|delete
    • -a (Optional) Set to allow to grant authorization or deny to revoke.
  1. Log in as the new user

    $ ssrun login -u NewUser -p NewUserPassword

  2. Read the secret

    $ ssrun secret get testsecret:mytestsecret

  3. Login as root again

    $ ssrun login -u root -p rootpassword

  4. Delete the new user

    $ ssrun user delete -n NewUser

Manage Applications

Before starting this section, ensure you have initialized, unsealed, and logged into DevOps Secrets Safe as root.

For more information about how to log into DSS as root, please see the Initialize DevOps Secrets Safe section.

  1. Create a new application

    $ ssrun application create -n NewApplication

Upon creation, an API key will be returned. This will be used in any subsequent log in.

  1. View the list of applications

    $ ssrun application get -v

The principal discovery mechanism in the API accepts any subset of the URI {identity_provider}/{principal_type}/{principal_name}/{principal_extension_data}. Therefore, the command above will return all internal applications. Additionally, the (optional) -v flag can be used to get a full listing of principals or principal containers attributes. Otherwise, a slim view of each principal or principal container is returned.

  1. Create a secret

    $ echo -n "I love my test content" | ssrun secret create testsecret:mytestsecret

Whenever you reference a secret, the URI must be in the format {scopePath}:{secretName}. For example, path/to/secrets:secretName.

For more information on managing secrets, please see the Manage Secrets and Scopes section.

  1. Authorize the new application to read the secret
    $ ssrun authorization create -p principal/internal/application/NewApplication -o read -a allow secret/testsecret:mytestsecret

    The authorize command accepts the following arguements:

    • -p (Required) URI of the principal the access control is being applied to.
      • An applications URI can be derived using the principal discovery mechanism detailed in step 2.
    • -o (Required) Operations authorization applies to.
      • Options are create|read|update|delete -
    • -a (Required) Set to allow to grant authorization or deny to revoke.
  2. Log in as the new application

    $ ssrun login -a NewApplication -k 2a098f21-0b11-4918-b705-7752588d5d8c

The API key -k comes from what was returned when the application was created.

  1. Read the secret

    $ ssrun secret get testsecret:mytestsecret

  2. Login as root again

    $ ssrun login -u root -p rootpassword

  3. Delete the new application

    $ ssrun application delete -n NewApplication

The name associated with an application can be determined via the list applications command as detailed in step 2.

Manage Secrets and Scopes

Before starting this section, ensure you have initialized, unsealed and logged into DevOps Secrets Safe as root.

For more information about how to log into DSSas root, please see the Initialize DevOps Secrets Safe section.

The next example assumes there are two files called myTestSecretData1.txt and myTestSecretData2.txt containing data you want to be stored as a secret.

  1. Create two secrets

    $ ssrun secret create -f myTestSecretData1.txt path/to/my/secrets:mytestsecret1

    $ ssrun secret create -f myTestSecretData2.txt path/to/my/secrets:mytestsecret2

Whenever you reference a secret, the URI must be in the format {scopePath}:{secretName}. For example, path/of/scope:secretName.

  1. Retrieve the list of secret names for a given scope

    $ ssrun scope get path/to/my/secret

The next example assumes there is a file called updatedMyTestSecretData1.txt containing the data you want to use to update this secret.

  1. Update a secret

    $ ssrun secret update -f updatedMyTestSecretData1.txt path/to/my/secrets:mytestsecret1

  2. Retrieve a secret

    $ ssrun secret get path/to/my/secrets:mytestsecret1

  3. Remove a secret

    $ ssrun secret delete path/to/my/secrets:mytestsecret1

This will not only remove the secret but also all metadata that is associated with it.

  1. Remove a scope

    $ ssrun secret delete path/to/my/secrets

This will not only remove the scope but also all scopes, secrets and metadata that is a child of it.

Manage Metadata

Before starting this section, ensure you have initialized, unsealed and logged into DevOps Secrets Safe as root.

For more information about how to log into DSS as root, please see the Initialize DevOps Secrets Safe section.

  1. Create metadata for a secret
    $ ssrun metadata create -n mytestsecret1Meta1Name -v meta1Value path/to/my/secrets:mytestsecret1

When managing metadata, to reference a scope, set the URI to its path. For example, path/of/scope. To reference a secret, use {path}:{secretName}. For example, path/of/scope:secretName.

  1. Update metadata for a secret
    $ ssrun metadata update -n mytestsecret1Meta1Name -v updatedMeta1Value path/to/my/secrets:mytestsecret1
  2. View metadata for a secret

    $ ssrun metadata get -n mytestsecret1Meta1Name path/to/my/secrets:mytestsecret1

The above command will simply retrieve the information associated with the metadata item named mytestsecret1Meta1Name. To retrieve the information for all metadata items associated with a scope or secret omit the -n argument.

  1. Remove metadata

    $ ssrun metadata delete -n mytestsecret1Meta1Name path/to/my/secrets:mytestsecret1

Manage Safelists and IP Ranges

Before starting this section, ensure you have initialized, unsealed and logged into DevOps Secrets Safe as root.

For more information about how to log into DSS as root, please see the Initialize DevOps Secrets Safe section.

Safelists allow you to explicitly grant or deny access to specific IP addresses for all CLI commands. Safelists and IP ranges must be structured in the following way:

  • Name - (Required) Name for this safelist.
    • Names must be unique and can only include the following characters: 0-9, A-Z, a-z, underscore (_) and dash (-)
  • Description - (Optional) Details about this safelist
  • Expiry date - (Optional) Specifies a day and time when this safeList will expire.
    • An empty or null value denotes no expiry.
  • Name - (Required) Name for this IP range.
    • Names must be unique to their parent safelist and can only include the following characters: 0-9, A-Z, a-z, underscore (_) and dash (-) .
  • Value - (Required) Specifies a range of IP addresses.
    • The supported IP range value patterns are:
      • CIDR range: "192.168.0.0/24", “fe80::%lo0/10”
      • Single address: "10.101.8.16", “fe80::1%23”
      • Begin-end range: "10.101.8.10-10.101.8.20", “fe80::1%23-fe80::ff%23”
  • Allow - (Required) Specifies whether the defined range of IP addresses should be used to allow or deny access.
  • Description - (Optional) Details about this IP range
  • Expiry date - (Optional) Specifies a day and time when this IP range will expire.
    • An empty or null value denotes no expiry.

A safelist must have at least one IP range associated with it.

  1. Create two safelists

    $ ssrun safelist create -f safelist1.txt

    $ ssrun safelist create -f safelist2.txt

This example assumes there are two files called safelist1.txt and safelist2.txt with the following contents:

safelist1.txt

{
   "ipRanges": [
      {
         "name": "ip_range_1",
         "value": "10.101.8.10-10.101.8.20",
         "allow": true,
         "description": "IP Range 1 Description",
         "expiryDate": "2020-06-21T11:44:31.733Z",
         "xForwardedForHeaderLimit": "2"
      }
   ],
   "name": "safelist_1",
   "description": "Safelist 1 Description",
   "expiryDate": "2020-06-21T11:44:31.733Z"
}

In the above example, the safelist will only be enforced until the defined expiry date and will allow only IP addresses in the range of 10.101.8.10 to 10.101.8.20.

safelist2.txt

{
   "ipRanges": [
      {
         "name": "ip_range_2",
         "value": "10.101.8.50-10.101.8.60",
         "allow": false,
         "description": "IP Range 2 Description",
      }
   ],
   "name": "safelist_2",
   "description": "Safelist 2 Description",
}

In the above example, the safelist will never expire and will deny IP addresses in the range of 10.101.8.50 to 10.101.8.60.

  1. View safelists and ip ranges

    The safelist get command will return all safelists that exist.

    $ ssrun safelist get

    You can also limit the view by passing in the name of the safelist targeted for discovery.

    $ ssrun safelist get -s safelist_1

    The ip-range get command will return all the ip ranges that exist for a given safelist.

    $ ssrun ip-range get -s safelist_1

    You can also limit the view by passing in the name of the ip range targeted for discovery.

    $ ssrun ip-range get -s safelist_1 -i ip_range_1

    Views can be further modified by using the following flags:

    • -d - (Depth) Use this to define the maximum depth of the view to return.
      • A value of 0 returns only the element specified.
      • A value of 1 returns the element specified and all direct children.
      • A value of 2 returns all children and grandchildren of the element specified
    • -v (Verbose) Use this to get a full listing of safelists and/or ip ranges attributes.
      • Otherwise, a slim view of each safeLists and/or ip ranges is returned.
  2. Update a safelist

    $ ssrun safelist update -s safelist_2 -f safelist2Update.txt

    This command will update the safelist with name safelist_2.

The example assumes there is a file called safelist2Update.txt with the following contents:

safelist2Update.txt

{
    "description": "Safelist 2 Description Updated",
    "expiryDate": "2021-06-21T12:17:14.326Z"
}
  1. Add an IP range to a safelist

    $ ssrun ip-range create -s safelist_2 -f ipRange.txt

    This command will add an IP range to the safelist with name safelist_2.

The example assumes there is a file called ipRange.txt with the following contents:

ipRange.txt

{
    "value": "10.101.8.70",
    "allow": false,
    "description": "IP Range 3 Description",
    "expiryDate": "2021-06-21T11:58:03.315Z"
}

In the above example, the IP range will only be enforced until the defined expiry date and will deny IP requests coming from the IP address 10.101.8.70

  1. Update an IP range of a safelist

    $ ssrun ip-range update -s safelist_2 -i ip_range_2 -f ipRangeUpdate.txt

    This command will update the IP range with name ip_range_2 for the safelist with name safelist_2.

The example assumes there is a file called ipRangeUpdate.txt with the following contents:

ipRangeUpdate.txt

{
    "value": "10.101.8.71",
    "allow": false,
    "description": "IP Range 3 Updated",
    "expiryDate": "2021-06-21T11:58:03.315Z"
}
  1. Assign a safelist to a user
    $ ssrun authorization create -p principal/internal/user/user1 -o read -a allow safelist/safelist_2/access

    This command will associate the safelist with name safelist_2 to the user with name user1.

  2. Delete an IP range from a safelist

    $ ssrun ip-range delete -s safelist_2 -i ip_range_2

    This command will delete the IP range with name ip_range_2 from the safelist with name safelist_2

  3. Delete a safelist

    $ ssrun safelist delete -s safelist_2

    This command will delete the safelist with name safelist_2

Manage Event Sink Configurations

Create an event sink configuration.

ssrun event-sink create -f myconfig.json

This command creates an event sink configuration using the provided JSON file.

Detailed instructions on event sink configuration can be found in the event sink configuration section of Event Sinks.