server

README

Voucher Server API Reference

This is a quick guide to the Voucher API, for developers who are looking at building in support for Voucher.

API Calls

POST /all

Run all of the enabled tests on the image referred to by the passed input.

Depending on the server's configuration, your client may need to use Basic Authentication to access this call.

This call accepts a JSON encoded object with the following fields:

Field	Comment
image_url	The URL of the image to test against. This should include the digest at the end of the URL.

For example:

{
   "image_url": "gcr.io/path/to/image@sha256:hashvalue",
}

The response will be a JSON encoded object containing the same fields, as well as a listing of the tests that ran, if they were successful or not, and any errors returned during the course of the test execution.

The response will have the following fields:

Field	Comment
image	The URL of the image to test against.
success	A boolean, true if all tests passed, false if anyh failed.
results	An array of objects, with one for each test that was executed.

The each of the objects in the results array are structured as follows:

Field	Comment
name	The name of the test.
success	A boolean, true if all tests passed, false if any of the tests failed.
attested	A boolean, true if an attestation was created for the check.
err	Any error message or structure that was thrown during the course of the execution.

POST /all/verify

Verify the existence of attestations on the passed image for all enabled checks.

The input and output of this API call is identical to that described in POST /all, and like that call, authorization may be handled by Basic Authentication.

POST /{test name here}

Run the test specified in the URL.

For example, if the API call is POST /diy, this will run the DIY test and nothing else.

This can also be used to run all tests required for an environment as specified in the configuration.

For example, if the API call is POST /myenv, this will run the all tests enabled for myenv.

The input and output of this API call is identical to that described in POST /all, and like that call, authorization may be handled by Basic Authentication.

POST /{test name here}/verify

Verify the existence of attestations for the passed check or check group.

For example, if the API call is POST /diy/verify, this will verify the passed image reference has a DIY attestation.

Likewise this API call can also be used to verify the existence of attestations for all tests required for an environment as specified in the configuration.

For example, if the API call is POST /myenv/verify, this will verify that an attestation exists for each of the checks enabled for myenv.

The input and output of this API call is identical to that described in POST /all/verify, and like that call, authorization may be handled by Basic Authentication.

GET /services/ping

This call does nothing more than return a 200 Success status code. It is used to verify that the service is online.

No Authorization header is required.

Documentation

Index

• func LogError(message string, err error)
• func LogInfo(message string)
• func LogRequests(r *http.Request)
• func LogResult(response voucher.Response)
• func LogWarning(message string, err error)
• func NewRouter(s *Server) *mux.Router
• type Config
  • func (config *Config) Address() string
  • func (config *Config) TimeoutDuration() time.Duration
• type Route
• type Server
  • func NewServer(config *Config, secrets *config.Secrets, metrics metrics.Client) *Server
  • func (server *Server) GetCheckGroup(name string) []string
  • func (s *Server) HandleCheckImage(w http.ResponseWriter, r *http.Request)
  • func (s *Server) HandleHealthCheck(w http.ResponseWriter, r *http.Request)
  • func (s *Server) HandleVerifyImage(w http.ResponseWriter, r *http.Request)
  • func (server *Server) HasCheckGroup(name string) bool
  • func (server *Server) Serve()
  • func (server *Server) SetCheckGroup(name string, checkNames []string)

Functions

func LogError

func LogError(message string, err error)

LogError logs server errors to stdout as Error

func LogInfo

func LogInfo(message string)

LogInfo logs server information to stdout as Information.

func LogRequests

func LogRequests(r *http.Request)

LogRequests logs the request fields to stdout as Info

func LogResult

func LogResult(response voucher.Response)

LogResult logs each test run as Info

func LogWarning

func LogWarning(message string, err error)

LogWarning logs server errors to stdout as Warning

func NewRouter

func NewRouter(s *Server) *mux.Router

NewRouter creates a mux router with the specified routes and handlers

Types

type Config

type Config struct {
	Port        int
	Timeout     int
	RequireAuth bool
	Username    string
	PassHash    string
}

Config is a structure which contains Server configuration.

func (*Config) Address

func (config *Config) Address() string

Address is the address of the Server.

func (*Config) TimeoutDuration

func (config *Config) TimeoutDuration() time.Duration

TimeoutDuration returns the configured timeout for this Server.

type Route

type Route struct {
	Name        string
	Method      string
	Path        string
	HandlerFunc http.HandlerFunc
}

Route stores metadata about a particular endpoint

type Server

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

func NewServer

func NewServer(config *Config, secrets *config.Secrets, metrics metrics.Client) *Server

NewServer creates a server on the specified port

func (*Server) GetCheckGroup

func (server *Server) GetCheckGroup(name string) []string

GetCheckGroup returns a list of checks names that are in the check group with the passed name.

func (*Server) HandleCheckImage

func (s *Server) HandleCheckImage(w http.ResponseWriter, r *http.Request)

HandleCheckImage is a request handler that executes an individual Check or all of the Checks in one CheckGroup and creates any attestations if applicable.

func (*Server) HandleHealthCheck

func (s *Server) HandleHealthCheck(w http.ResponseWriter, r *http.Request)

HandleHealthCheck is a request handler that returns HTTP Status Code 200 when it is called. Can be used to determine uptime.

func (*Server) HandleVerifyImage

func (s *Server) HandleVerifyImage(w http.ResponseWriter, r *http.Request)

HandleVerifyImage is a request handler that verifies an individual attestation or all of the attestations which would be created by one CheckGroup and creates any attestations if applicable.

func (*Server) HasCheckGroup

func (server *Server) HasCheckGroup(name string) bool

HasCheckGroup returns true if the Check Group with the passed name has been registered with the server.

func (*Server) Serve

func (server *Server) Serve()

Serve runs the Server on the specified port

func (*Server) SetCheckGroup

func (server *Server) SetCheckGroup(name string, checkNames []string)

SetCheckGroup adds a list of checks as a group with the passed name.