cerberus

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 9, 2017 License: Apache-2.0 Imports: 11 Imported by: 0

README

Cerberus Go Client

A Golang client for accessing Cerberus. To learn more about Cerberus, please visit the Cerberus Website

Usage

Quick Start

The simplest way to get started is to use the user authentication:

import (
	"fmt"

	cerberus "github.com/Nike-Inc/cerberus-go-client"
	"github.com/Nike-Inc/cerberus-go-client/auth"
)
...
authMethod, _ := auth.NewUserAuth("https://cerberus.example.com", "my-cerberus-user", "my-password")
// This will prompt you for an MFA token if you have MFA enabled
client, err := cerberus.NewClient(authMethod, nil)
if err != nil {
    panic(err)
}
sdbs, _ := client.SDB().List()
fmt.Println(sdbs)
Supported endpoints

All of the most recent endpoints at the time of writing (2 May 2017) are supported while older versions are not. The full list is below

  • /v2/auth/user
  • /v2/auth/mfa_check
  • /v2/auth/user/refresh
  • /v2/auth/iam-principal
  • /v1/auth (used for DELETE operations)
  • /v2/safe-deposit-box
  • /v1/role
  • /v1/category
  • /v1/metadata
Authentication

Cerberus supports 3 types of authentication, all of which are explained below. The auth types are designed to be used independently of the full Cerberus client if desired. This allows you to just get a token for use in other applications. There are also methods for returning a set of headers needed to authenticate to Cerberus. With all of the authentication types, GetToken triggers the actual authentication process for the given type.

All 3 types support setting the URL for Cerberus using the CERBERUS_URL environment variable, which will always override anything you pass to the New*Auth methods.

AWS

AWS authentication expects an IAM principal ARN and an AWS region to be able to authenticate. For more information, see the API docs

authMethod, _ := auth.NewAWSAuth("https://cerberus.example.com", "arn:aws:iam::111111111:role/cerberus-api-tester", "us-west-2")
tok, err := authMethod.GetToken(nil)
Token

Token authentication is meant to be used when there is already an existing Cerberus token you wish to use. No validation is done on the token, so if it is invalid or expired, method calls will likely return an api.ErrorUnauthorized.

This method also allows you to set a token using the CERBERUS_TOKEN environment variable. Like CERBERUS_URL, this will override anything you pass to the NewTokenAuth method.

authMethod, _ := auth.NewTokenAuth("https://cerberus.example.com", "my-cool-token")
tok, err := authMethod.GetToken(nil)
User

User authentication is for using a username and password (with optional MFA) to log in to Cerberus. There are some known limitations with MFA. The GetToken method takes an *os.File argument that expects a file with one line containing the MFA token to use. Otherwise, if nil is passed it will prompt for the MFA token.

authMethod, _ := auth.NewUserAuth("https://cerberus.example.com", "my-cerberus-user", "my-password")
tok, err := authMethod.GetToken(nil)
Client

Once you have an authentication method, you can pass it to NewClient along with an optional file argument for where to read the MFA token from. NewClient will take care of actually authenticating to Cerberus

client, err := cerberus.NewClient(authMethod, nil)

The client is organized with various "subclients" to access different endpoints. For example, to list all SDBs and secrets for each SDB:

list, err := client.SDB().List()
for _, v := range list {
    l, _ := client.Secret().List(v.Path)
    fmt.Println(l)
}

For full information on every method, see the Godoc

Development

Code organization

The code is broken up into 4 parts, including 3 subpackages. The top level package contains all of the code for the Cerberus client proper. A breakdown of all the subpackages follows:

API

The api package contains all type definitions for API objects as well as common errors. It also contains API error handling methods

Auth

The auth package contains implementations for all authentication types and the definition for the Auth interface that all authentication types must satisfy.

Utils

The utils package contains common methods used by the top level client and multiple subpackages. This is not meant to be a kitchen sink in which to throw things that don't belong.

Tests

We use GoConvey for our testing. There are plenty of tests in the code that you can use for examples

Contributing

See the CONTRIBUTING.md document for more information on how to begin contributing.

The tl;dr is that we encourage any PRs you'd like to submit. Please remember to keep your commits small and focused and try to write tests for any new features you add.

Roadmap

All endpoints have been implemented with unit tests. The other major task remaining is to write integration tests.

Known limitations

Currently, this will only support one enrolled MFA device (the first one you enable). In the future we want to make this cleaner for CLI usage

Full example

Below is a full, runnable example of how to use the Cerberus client with a simple CLI

package main

import (
	"fmt"
	"os"

	cerberus "github.com/Nike-Inc/cerberus-go-client"
	"github.com/Nike-Inc/cerberus-go-client/api"
	"github.com/Nike-Inc/cerberus-go-client/auth"
	"golang.org/x/crypto/ssh/terminal"
)

func main() {
	var username string
	fmt.Print("Input username: ")
	fmt.Scan(&username)
	fmt.Print("Input password: ")
	password, _ := terminal.ReadPassword(0)
	fmt.Print("\n")
	authMethod, err := auth.NewUserAuth("https://cerberus.example.com", username, string(password))
	if err != nil {
		fmt.Printf("Error when creating auth method: %v\n", err)
		os.Exit(1)
	}

	client, err := cerberus.NewClient(authMethod, nil)
	if err != nil {
		fmt.Printf("Error when creating client: %v\n", err)
		os.Exit(1)
	}
	tok, _ := client.Authentication.GetToken(nil)
	fmt.Println(tok)

	sdb, err := client.SDB().GetByName("TestBoxForScience")
	if err != nil {
		fmt.Printf("Error when getting sdb: %v\n", err)
		os.Exit(1)
	}

	fmt.Println(sdb)

	sec, err := client.Secret().List(sdb.Path)
	if err != nil {
		fmt.Printf("Error when getting secrets: %v\n", err)
		os.Exit(1)
	}
	fmt.Println(sec)

	newSDB, err := client.SDB().Create(&api.SafeDepositBox{
		Name:        "testtest",
		Description: "A test thing",
		Owner:       "Lst.test.cerberus",
		CategoryID:  sdb.CategoryID,
	})
	if err != nil {
		fmt.Printf("Error when creating SDB: %v\n", err)
		os.Exit(1)
	}
	fmt.Println(newSDB)

	if err := client.SDB().Delete(newSDB.ID); err != nil {
		fmt.Printf("Error when deleting SDB: %v\n", err)
		os.Exit(1)
	}
}

Maintainers

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrorBodyNotReturned = fmt.Errorf("No error body returned from server")

ErrorBodyNotReturned is an error indicating that the server did not return error details (in case of a non-successful status). This likely means that there is some sort of server error that is occurring

View Source 
var ErrorSafeDepositBoxNotFound = fmt.Errorf("Unable to find Safe Deposit Box")

ErrorSafeDepositBoxNotFound is returned when a specified deposit box is not found

Functions

This section is empty.

Types

type Category 

type Category struct {
	// contains filtered or unexported fields
}

Category is a subclient for accessing the category endpoint

func (*Category) List 

func (r *Category) List() ([]*api.Category, error)

List returns a list of roles that can be granted

type Client 

type Client struct {
	Authentication auth.Auth
	CerberusURL    *url.URL
	// contains filtered or unexported fields
}

Client is the main client for interacting with Cerberus

func NewClient 

func NewClient(authMethod auth.Auth, otpFile *os.File) (*Client, error)

NewClient creates a new Client given an Authentication method. This method expects a file (which can be nil) as a source for a OTP used for MFA against Cerberus (if needed). If it is a file, it expect the token and a new line.

func (*Client) Category 

func (c *Client) Category() *Category

Category returns the Category client

func (*Client) DoRequest 

func (c *Client) DoRequest(method, path string, params map[string]string, data interface{}) (*http.Response, error)

DoRequest is used to perform an HTTP request with the given method and path This method is what is called by other parts of the client and is exposed for advanced usage

func (*Client) Metadata 

func (c *Client) Metadata() *Metadata

Metadata returns the Metadata client

func (*Client) Role 

func (c *Client) Role() *Role

Role returns the Role client

func (*Client) SDB 

func (c *Client) SDB() *SDB

SDB returns the SDB client

func (*Client) Secret 

func (c *Client) Secret() *Secret

Secret returns the Secret client

type Metadata 

type Metadata struct {
	// contains filtered or unexported fields
}

Metadata is a subclient for accessing the metadata endpoint

func (*Metadata) List 

func (m *Metadata) List(opts MetadataOpts) (*api.MetadataResponse, error)

List returns a MetadataResponse which is a wrapper containing pagination data and an array of metadata objects

type MetadataOpts 

type MetadataOpts struct {
	Limit  uint
	Offset uint
}

MetadataOpts is used for passing pagination values to the list function

type Role 

type Role struct {
	// contains filtered or unexported fields
}

Role is a subclient for accessing the roles endpoint

func (*Role) List 

func (r *Role) List() ([]*api.Role, error)

List returns a list of roles that can be granted

type SDB 

type SDB struct {
	// contains filtered or unexported fields
}

SDB is a client for managing and reading SafeDepositBox objects

func (*SDB) Create 

func (s *SDB) Create(newSDB *api.SafeDepositBox) (*api.SafeDepositBox, error)

Create creates a new Safe Deposit Box and returns the newly created object

func (*SDB) Delete 

func (s *SDB) Delete(id string) error

Delete deletes the Safe Deposit Box with the given ID

func (*SDB) Get 

func (s *SDB) Get(id string) (*api.SafeDepositBox, error)

Get returns a single SDB given an ID. Returns ErrorSafeDepositBoxNotFound if the ID does not exist

func (*SDB) GetByName 

func (s *SDB) GetByName(name string) (*api.SafeDepositBox, error)

GetByName is a helper method that takes a SDB name and attempts to locate that box in a list of SDBs the client has access to

func (*SDB) List 

func (s *SDB) List() ([]*api.SafeDepositBox, error)

List returns a list of all SDBs the authenticated user is allowed to see

func (*SDB) Update 

func (s *SDB) Update(id string, updatedSDB *api.SafeDepositBox) (*api.SafeDepositBox, error)

Update updates an existing Safe Deposit Box. Any fields that are not null in the passed object will overwrite any fields on the current object

type Secret 

type Secret struct {
	// contains filtered or unexported fields
}

Secret wraps the vault.Logical client to make sure all paths are prefaced with "secret". This does not expose Unwrap because it will not work with Cerberus' path routing

func (*Secret) Delete 

func (s *Secret) Delete(path string) (*vault.Secret, error)

Delete deletes the given path. Path should not be prefaced with a "/"

func (*Secret) List 

func (s *Secret) List(path string) (*vault.Secret, error)

List lists secrets at the given path. Path should not be prefaced with a "/"

func (*Secret) Read 

func (s *Secret) Read(path string) (*vault.Secret, error)

Read returns the secret at the given path. Path should not be prefaced with a "/"

func (*Secret) Write 

func (s *Secret) Write(path string, data map[string]interface{}) (*vault.Secret, error)

Write creates a new secret at the given path. Path should not be prefaced with a "/"

Source Files

View all Source files

Directories

Path Synopsis
Package api contains the Cerberus API object definitions This is not a full implementation of every object right now and only defines the needed objects for the client to function.
 Package api contains the Cerberus API object definitions This is not a full implementation of every object right now and only defines the needed objects for the client to function.
Package auth contains various implementations for authenticating with Cerberus.
 Package auth contains various implementations for authenticating with Cerberus.
Package utils contains common functionality needed across the Cerberus Go client
 Package utils contains common functionality needed across the Cerberus Go client

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.