Documentation ¶
Overview ¶
Package sophos is a Sophos UTM 9 REST API Client
Index ¶
- Constants
- Variables
- func AutoResolveErrsMode(r *http.Request) error
- func CancelResolveErrsMode(r *http.Request) error
- func IsFatalErr(err error) bool
- func IsReference(ref string) bool
- func Request(method, path string, body io.Reader, options ...Option) (*http.Request, error)
- func WithRestdLockOverride(r *http.Request) error
- func WithSessionClose(r *http.Request) error
- type Client
- func (c Client) Delete(path string, options ...Option) (*Response, error)
- func (c Client) DeleteObject(o RestObject, options ...Option) error
- func (c Client) Do(method, path string, body io.Reader, options ...Option) (resp *Response, err error)
- func (c Client) Endpoint() string
- func (c Client) Get(path string, options ...Option) (*Response, error)
- func (c Client) GetEndpointSwag(e Endpoint, options ...Option) (Swag, error)
- func (c Client) GetObject(o RestGetter, options ...Option) error
- func (c Client) GetUsedBy(o RestObject, options ...Option) (*UsedBy, error)
- func (c Client) Patch(path string, body io.Reader, options ...Option) (*Response, error)
- func (c Client) PatchObject(o RestObject, options ...Option) error
- func (c Client) Ping(options ...Option) (v *Version, err error)
- func (c Client) Post(path string, body io.Reader, options ...Option) (*Response, error)
- func (c Client) PostObject(o RestObject, options ...Option) error
- func (c Client) Put(path string, body io.Reader, options ...Option) (*Response, error)
- func (c Client) PutObject(o RestObject, options ...Option) error
- func (c *Client) Request(method, path string, body io.Reader, options ...Option) (*http.Request, error)
- type ClientInterface
- type Definition
- type Endpoint
- type Error
- type Errors
- type HTTPClient
- type MethodDescriptions
- type MethodMap
- type Node
- type Object
- type ObjectClient
- type Option
- type Parameter
- type Reference
- type Response
- type RestGetter
- type RestObject
- type Swag
- type UsedBy
- type Version
Constants ¶
const ( // XRestdErrAck is an http.Header key. // As described, there are multiple RESTful API interactions that can fail due to incon // sistencies, e.g., object A references object B but object B is deleted. The RESTful API // will prevent damage and inconsistency to confd by returning an error. // // You can resolve this problem by removing the reference to object B. You can configure // confd to Do this automatically by setting the header value to “last”. // X-Restd-Err-Ack: last // To enable this globally for all non-fatal errors, you can set the header value to “all.” // X-Restd-Err-Ack: all // // Note – Use this setting only when you’re not deleting important data or objects. Other // wise, you can acknowledge the error and cancel the operation by setting the header // value to “none”. You can then troubleshoot the error with all data and objects saved. // X-Restd-Err-Ack: none // // Refer to Section 3.4 of Sophos documentation XRestdErrAck = "X-Restd-Err-Ack" // XRestdLockOverride is an http.Header key. // The confd object model supports locking objects to avoid unintended changes. To // check if an object is locked or unlocked, you can use the GET method. The response // will indicate the specific lock level, i.e., “_locked” can be set to “global”, “user”, or “” // (empty string). A “global” value is a system lock and cannot be changed. A “user” value // is a lock set by a specific user while an empty string indicates that no lock is set. // // In order to change “user” lock values, you can change the lock value to an empty string // and then modify the “user” value. This procedure involves three API calls and can be // error prone if these calls are interrupted or not completed in the correct order. The // lock override header allows the users to manually override the current value without // having to change the value multiple times. // // X-Restd-Lock-Override: yes // // Refer to Section 3.5 of Sophos documentation XRestdLockOverride = "X-Restd-Lock-Override" // XRestdInsert is an http.Header key. // In many cases when you create a new object, the object needs to be directly inserted // into a node in order to be active. This usually takes two operations; however, there is // an additional header you can use when creating objects to automatically activate the // objects. The header will insert a reference at the given position inside the node. // // For example, if you create a “packetfilter/packetfilter” rule object and need to add the // object into the “packetfilter.rules” node and make it active, you can use the “1” flag to // set the rule as the first rule. If you need to add the new rule object as the last rule, you // can use “-1” flag. If you need the new rule object to reside somewhere in the middle, // e.g., fourth rules, you can set the flag to “4”. // // X-Restd-Insert: packetfilter.rules 4 // // Refer to Section 3.6 of Sophos documentation XRestdInsert = "X-Restd-Insert" // XRestdSession is an http.Header key. // Each interaction with the confd creates or reuses a session. Sessions are important // for validation interaction and performance. However, maintaining sessions are // resource intensive and can degrade performance. If you use the RESTful API to auto // matically create a set or predefined rules, by default Sophos UTM will maintain those // sessions expecting additional API calls. You can close sessions if after creating your // rules you don’t anticipate subsequent API calls for the same process. At the last step, // you can set a header that will close the session. // X-Restd-Session: close // // Note – X-Restd-Session: close may cause a longer time for the next request. // Be sure to only send this command with the last request. // // Refer to Section 3.7 of Sophos documentation XRestdSession = "X-Restd-Session" // Authorization is the Authorization http.Header key Authorization = "Authorization" )
const ( // RefServiceAny is a well-known Reference referring to any UTM Service RefServiceAny = "REF_ServiceAny" // RefNetworkAny is a well-known Reference referring to any UTM Network RefNetworkAny = "REF_NetworkAny" // RefNtpPool is a well-known Reference referring to the NTP Pool RefNtpPool = "REF_NtpPool" // RefDefaultSuperAdminGroup is a Reference to the UTM's Default Super Admin Group RefDefaultSuperAdminGroup = "REF_DefaultSuperAdminGroup" // RefDefaultServiceWebAdmin is a well-known Reference RefDefaultServiceWebAdmin = "REF_DefaultServiceWebadmin" // RefDefaultServiceSpamrelease is a well-known Reference RefDefaultServiceSpamrelease = "REF_DefaultServiceSpamrelease" // RefDefaultHTTPCFFBlockAction is a well-known Reference RefDefaultHTTPCFFBlockAction = "REF_DefaultHTTPCFFBlockAction" // RefDefaultHTTPPACFile is a well-known Reference RefDefaultHTTPPACFile = "REF_DefaultHTTPPACFile" // RefDefaultHTTPProfile is a well-known Reference RefDefaultHTTPProfile = "REF_DefaultHTTPProfile" // RefDefaultPPTPPool is a well-known Reference RefDefaultPPTPPool = "REF_DefaultPPTPPool" // RefDefaultSSLPool is a well-known Reference RefDefaultSSLPool = "REF_DefaultSSLPool" )
Variables ¶
var ErrRefRequired = errors.New("client: Reference is required")
ErrRefRequired is an error that is returned when the resource requires a Referencee to fetch data
Functions ¶
func AutoResolveErrsMode ¶
AutoResolveErrsMode is an Option which sets the X-Restd-Err-Ack header to 'all' which will auto resolve all non-fatal errors. e.g. deleting sub-dependencies.
func CancelResolveErrsMode ¶
CancelResolveErrsMode is an Option which sets the X-Restd-Err-Ack header to 'none' which will automatically acknowledge the error and cancel the operation. Use this setting only when you’re not deleting important data or objects.
func IsFatalErr ¶ added in v0.1.0
IsFatalErr returns true if the error is an Error and is fatal
func IsReference ¶ added in v0.0.6
IsReference returns true if the string has the prefex "REF_"
func Request ¶ added in v0.0.9
Request generates a new *http.Request that is modified with the Client's Options (set on New) and with the provided Options.
func WithRestdLockOverride ¶
WithRestdLockOverride is an Option which sets the X-Restd-Lock-Override to yes.
func WithSessionClose ¶
WithSessionClose is an Option which sets the X-Restd-Session to close, be sure to only send this command with the last request.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements ClientInterface to provide a REST client
func (Client) Delete ¶
Delete executes a DELETE call
You can use DELETE requests to destroy object resources that were created with POST or PUT requests. Confd may deny DELETE requests due to validation checks. To use confd auto correction, use the special headers described X-Restd-Err-Ack header.
DELETE /api/objects/packetfilter/packetfilter/REF_PacPacAllowAnyFTPOut
func (Client) DeleteObject ¶ added in v0.0.2
func (c Client) DeleteObject(o RestObject, options ...Option) error
DeleteObject DELETEs the RestObject
func (Client) Do ¶
func (c Client) Do(method, path string, body io.Reader, options ...Option) (resp *Response, err error)
Do executes the call and returns a *Response
func (Client) Get ¶
Get requests are used to retrieve information. The GET request cannot modify the data from confd.
Examples for GET calls: GET /api/nodes GET /api/nodes/webadmin.port GET /api/objects/network/network GET /api/objects/network/network/REF_NetNet100008
func (Client) GetEndpointSwag ¶ added in v0.0.6
GetEndpointSwag is syntactic sugar around an Endpoint Definition's GetSwag method.
func (Client) GetObject ¶ added in v0.0.2
func (c Client) GetObject(o RestGetter, options ...Option) error
GetObject implements TypeClient
func (Client) GetUsedBy ¶ added in v0.0.6
func (c Client) GetUsedBy(o RestObject, options ...Option) (*UsedBy, error)
GetUsedBy GETs the Objects UsedBy data
func (Client) Patch ¶
Patch executes a PATCH call
You can use PATCH requests to update fields on an existing object: PATCH /api/objects/packetfilter/packetfilter/REF_PacPacAllowAnyFTPOut
func (Client) PatchObject ¶ added in v0.0.2
func (c Client) PatchObject(o RestObject, options ...Option) error
PatchObject PATCHes the RestObject
func (Client) Post ¶
Post executes a POST call
You can use PUT and POST for creating new resources. POST will create a new resource with an auto generated REF_ string whereas PUT will create resource for the REF_ string. You can use PUT to update the same resource after creation. PUT and POST require that you set all mandatory attributes of an object or node. You may need to override changes by removing locks (see chapter X-Restd-Lock-Override header).
PUT /api/nodes/packetfilter.rules POST /api/objects/packetfilter/packetfilter PUT /api/objects/packetfilter/packetfilter/REF_PacPacAllowAnyFTPOut
func (Client) PostObject ¶ added in v0.0.2
func (c Client) PostObject(o RestObject, options ...Option) error
PostObject POSTs the RestObject
func (Client) Put ¶
Put executes a PUT call
You can use PUT and POST for creating new resources. POST will create a new resource with an auto generated REF_ string whereas PUT will create resource for the REF_ string. You can use PUT to update the same resource after creation. PUT and POST require that you set all mandatory attributes of an object or node. You may need to override changes by removing locks (see XRestdLockOverride header).
PUT /api/nodes/packetfilter.rules POST /api/objects/packetfilter/packetfilter PUT /api/objects/packetfilter/packetfilter/REF_PacPacAllowAnyFTPOut
type ClientInterface ¶
type ClientInterface interface { Get(path string, options ...Option) (*Response, error) Put(path string, body io.Reader, options ...Option) (*Response, error) Post(path string, body io.Reader, options ...Option) (*Response, error) Patch(path string, body io.Reader, options ...Option) (*Response, error) Delete(path string, options ...Option) (*Response, error) }
ClientInterface represents a Sophos 9 REST API client
type Definition ¶ added in v0.0.2
Definition represents a Swagger API endpoint You can use the Swagger API Documents to identify all the different RESTful API end points with descriptions for each object and node. GET /api/definitions
This returns a list of possible Swagger API definitions and you can define the call so the results are specific to different objects or nodes: GET /api/definitions/network
type Endpoint ¶ added in v0.0.4
type Endpoint interface { // Definition returns the endpoint Definition Definition() Definition // RestObjects returns a map of the Node's editable Objects RestObjects() map[string]RestObject // ApiRoutes returns all known Node paths ApiRoutes() []string }
An Endpoint represents a UTM endpoint which is defined by its definitions endpoint GET /api/definitions/aws
type Error ¶ added in v0.0.9
type Error struct { Oattrs []string `json:"Oattrs"` Attrs []interface{} `json:"attrs"` Class string `json:"class"` DelObject string `json:"del_object"` Fatal int64 `json:"fatal"` Format string `json:"format"` Msgtype string `json:"msgtype"` Name string `json:"name"` NeverHide int64 `json:"never_hide"` Objname string `json:"objname"` Perms string `json:"perms"` Ref string `json:"ref"` Rights string `json:"rights"` Type string `json:"type"` }
An Error is returned from the Endpoint when errors occur Confd validates all nodes and objects on change operations (e.g., create, update, delete). When you execute a RESTful API call, you may trigger some validation errors. Validation errors are:
- fatal
- non-fatal
Fatal errors indicate a programming error like wrong input or wrong type. Non-fatal errors indicate that the current operation has impact on other objects or nodes, which might be harmful.
For example, if you create a rule for “packetfilter/packetfilter”, you would need to ref erence the node “packetfiler/rules” and enable the status. If you deleted the rule after wards, confd would detect that a referenced rule of “packetfilter/rules” was still enabled and report an error. For more information on validation errors, see chapter X-Restd-Err-Ack header.
type Errors ¶ added in v0.0.9
type Errors []Error
Errors is a slice of type Error which is returned from the api
type HTTPClient ¶ added in v0.0.6
HttpClient is an interface which represents an http.Client
var DefaultHTTPClient HTTPClient
DefaultHTTPClient is the default http.Client used. Caller can modify Client (e.g. to allow SkipInsecure)
type MethodDescriptions ¶ added in v0.0.2
type MethodDescriptions struct { Description string Parameters []Parameter Tags []string Responses map[int]struct{ Description string } }
MethodDescriptions describes the endpoint
type MethodMap ¶ added in v0.0.2
type MethodMap map[string]MethodDescriptions
MethodMap is a map of Methods -> MethodDescriptions e.g. get: MethodDescriptions{}
type Node ¶
type Node interface { Get(c ClientInterface, oo ...Option) error Update(c ClientInterface, oo ...Option) error }
A Node is a resource within Sophos UTM that you can update but cannot create, delete, or move. Nodes are organized hierarchically as in a filesystem. An example of a node is the “Shell Access” service module within Sophos UTM (identified as the “ssh” node). To enable the Shell Access service, you can set the ssh.status leaf node.
Unlike filesystems which use a slash “/” to separate the different nodes, Sophos UTM RESTful API uses a dot “.” to separate different nodes. Nodes reference objects, for example “Shell Access” and have a leaf node of allowed_networks which is an array of references to network objects.
type Object ¶
type Object interface { // GetType returns the objects Type GetType() string }
An Object resides in collections, which you can create, change, or delete. The collections of objects are predefined into classes and types. A class describes the general purpose of the objects whereas the type describes the required data for the object. Some objects need to be referenced by a node, to work properly (e.g. packetfilter/packetfilter and packetfilter/nat).
For example, one of most used class is “network”. The network class describes objects like “host” for real hosts (e.g. 192.168.0.1) or “network” for subnets (e.g. 192.168.0.0/24). The collection of objects is always expressed with a class and a type, e.g. “network/host” or “network/network”.
type ObjectClient ¶ added in v0.0.6
type ObjectClient interface { GetObject(o RestGetter, options ...Option) error PutObject(o RestObject, options ...Option) error PatchObject(o RestObject, options ...Option) error PostObject(o RestObject, options ...Option) error DeleteObject(o RestObject, options ...Option) error GetUsedBy(o RestObject, options ...Option) (*UsedBy, error) GetEndpointSwag(e Endpoint, options ...Option) (Swag, error) }
ObjectClient is an interface with syntactic sugar dealing with Objects
type Option ¶
Option is a functional config that is used to modify outgoing requests.
func WithAPIToken ¶
WithAPIToken is an Option which sets the Authorization header to the provided token
func WithBasicAuth ¶
WithBasicAuth is an Option which sets the Authorization header to the provided username and password.
func WithContext ¶ added in v0.0.2
WithContext is an Option which sets the provided context to the the client's request.
func WithRestdInsert ¶
WithRestdInsert is an Option which adds the XRestdInsert header to insert a reference at the given position inside the node. X-Restd-Insert: packetfilter.rules 4
type Parameter ¶ added in v0.0.2
A Parameter defines the arguments that can be passed to the endpoint
type Reference ¶
type Reference string
A Reference is the connections between nodes and objects as well as between one object and another object. Each confd node and object has a list of attributes with pre defined types, where one of the types can be a reference. Please note however that you can’t create a reference in all cases. You can only make a reference in scenarios where nodes and objects are designed to be connected. Technically, references are strings that always start with the prefix “REF_”.
func (Reference) IsReference ¶ added in v0.0.4
IsReference returns true if the string has the prefex "REF_"
type Response ¶
type Response struct { *http.Response // Errors is a slice of type Error that != nil when http.StatusCode >= 400 <= 421 Errors *Errors }
Response contains the http.Response from the API
type RestGetter ¶ added in v0.0.2
type RestGetter interface { GetPath() string // GetPath returns the GET path of the Object, will sometimes require Reference RefRequired() (string, bool) // RefRequired returns true if Ref required }
RestGetter is an interface ensuring a Reference is passed when required Additionally used to GET pluralized Objects like objects.AmazonVpcConnections
type RestObject ¶
type RestObject interface { RestGetter DeletePath(ref string) string // DeletePath returns the DELETE path of the Object PatchPath(ref string) string // PatchPath returns the PATCH path of the Object PostPath() string // PostPath returns the POST path of the Object PutPath(ref string) string // GetPath returns the PUT path of the Object UsedByPath(ref string) string // UsedByPath returns the usedby URL path to query for UsedBy data }
RestObject is an interface for REST objects
type Swag ¶ added in v0.0.2
Swag represents a Swagger API document. The Swagger API document contains API endpoints along with parameters and object definitions for those endpoints. When objects have references to other objects the type is a regular string (REF_ string). Since not all references are allowed, each object has a description that states which subset of an object can be used as a reference. For example, the string REF(network/*) means that all network objects can be used as ref erences while REF(network/host) means that only network host objects can be used.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
api
|
|
v1.3.0/nodes
Package nodes contains generated types and Get/Update functions for sophos.Node(s) This file was generated by bin/gen.go! DO NOT EDIT!
|
Package nodes contains generated types and Get/Update functions for sophos.Node(s) This file was generated by bin/gen.go! DO NOT EDIT! |
v1.3.0/objects
Package objects contains the generated Sophos object types
|
Package objects contains the generated Sophos object types |
Program gen is used to generate go-sophos types
|
Program gen is used to generate go-sophos types |