Code Monkey home page Code Monkey logo

go-sophos's Introduction

go-sophos

Documentation Go Report Card codecov Build Status MIT License

A Sophos UTM REST API client for Go with zero dependencies.

Prerequisites

The Sophos UTM REST API must be enabled in Administrator settings.

Familiarity with the Sophos docs.

API types and functions are generated and versioned against UTM's declared Restd version.

Usage

API is stable as of 0.1.0

go get github.com/esurdam/go-sophos

Create a client:

import "github.com/esurdam/go-sophos"

// All Options passed on initialize will be applied to all subsequent calls
client, _ := sophos.New(
    "192.168.0.1:4848", 
    sophos.WithBasicAuth("user", "pass"),
)

Requesting the current port of the WebAdmin (see Nodes for more usage):

import "github.com/esurdam/go-sophos"

client, _ := sophos.New(
    "192.168.0.1:4848", 
    sophos.WithApiToken("abCDEFghIjklMNOPQkwSnwbutCpHdjQz"),
)
res, _ := client.Get("/api/nodes/webadmin.port")

var port int
res.MarshalTo(&port)
fmt.Println(port)
// Output: 4848

Nodes

Nodes are interacted with using pacakage level functions:

import "github.com/esurdam/go-sophos/api/v1.3.0/nodes"

v, err := nodes.GetWebadminPort(client)
fmt.Println(v)
// Output: 4848

err = nodes.UpdateWebadminPort(client, 4444)

Or as struct types with syntactic sugar around the functions, as represented by the Node interface:

import "github.com/esurdam/go-sophos/api/v1.3.0/nodes"

var wap nodes.WebadminPort
err := wap.Get(client)
fmt.Println(wap.Value)
// Output: 4848

wap.Value = 4444
err = wap.Update(client)

You can get the whole UTM node tree as an object as well:

import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

var nodes objects.Nodes
_ := client.GetObject(&nodes)

// active Ips
nodes.LicensingActiveIps 

Objects

Each file in the objects dir represents an Endpoint generated from a Definition and contains its generated Objects.

Objects implement the RestObject interface:

import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

var dns objects.Dns
err := client.GetObject(&dns)

Notice that some objects are pluralized and only implement the RestGetter interface:

import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

var ss objects.DnsRoutes
_ = client.GetObject(&ss)

// Each individual DnsRoute is therefore a RestObject
for _, s := range ss {
    ub, _ := client.GetUsedBy(&s)
    fmt.Printf("DNS ROUTE: %s [%s]\n  Used By Nodes: %v\n  Used by Objects: %v\n",s.Name, s.Reference, ub.Nodes, ub.Objects)
    // OUTPUT: DNS ROUTE: sophos.boom.local [REF_DnsRouBoomloca]
    //             Used By Nodes: [dns.routes]
    //             Used by Objects: []
}

Note that Endpoint types contain their Definition:

import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

fmt.Printf("%#v", objects.Dns{}.Definition())
// Output: sophos.Definition{
//  Description:"dns", 
//  Name:"dns", 
//  Link:"/api/definitions/dns"
// }

Requesting an Endpoint's Swag:

import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

// with sugar
var dns objects.Dns
swag, _ := client.GetEndpointSwag(dns)

// without sweets
d := objects.Dns{}.Definition()
swag, _ := d.GetSwag(client)

Examples

Examples from Sophos docs.

Deleting a packet filter rule with reference REF_PacPacXYZ:

This example uses the X-Restd-Err-Ack: all header to automatically approve the deletion of the object:

import "github.com/esurdam/go-sophos"

client, _ := sophos.New(
    "192.168.0.1:4848", 
    sophos.WithBasicAuth("user", "pass"),
)

_, err := client.Delete(
    "api/objects/packetfilter/packetfilter/REF_PacPacXYZ", 
    sophos.WithSessionClose, 
    sophos.AutoResolveErrsMode,
)

The same as above but using objects: [example]

import "github.com/esurdam/go-sophos"
import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

client, _ := sophos.New(
    "192.168.0.1:4848", 
    sophos.WithBasicAuth("user", "pass"),
)

// object knows api route
pf := objects.PacketfilterPacketfilter{
	Reference: "REF_PacPacXYZ"
}

err := client.DeleteObject(&pf, 
	sophos.WithSessionClose, 
	sophos.AutoResolveErrsMode
)

Creating a PacketFilter: [example]

import "github.com/esurdam/go-sophos"
import "github.com/esurdam/go-sophos/api/v1.3.0/objects"

client, _ := sophos.New(
    "192.168.0.1:4848", 
    sophos.WithBasicAuth("user", "pass"),
)

pf := objects.PacketfilterPacketfilter{
    Action:       "accept",
    Destinations: []string{sophos.RefNetworkAny},
    Direction:    "in",
    Log:          true,
    Services:     []string{sophos.RefServiceAny},
    Sources:      []string{sophos.RefNetworkAny},
    Status:       true,
}

err := client.PostObject(&pf, 
	sophos.WithRestdInsert("packetfilter.rules", 0), 
	sophos.WithSessionClose,
)

// successful creation will have unmarshalleed the Response
pf.Reference  

Errors

if err != nil {
    // for modifying requests (PATCH, PUT, POST, DELETE), err returned may be of type *sophos.Errors
    // see client.Do and Response type for how errors are parsed
    err.(*sophos.Errors).Error() == err.Error()
    sophos.IsFatalErr(err) == err.(*sophos.Errors).IsFatal()
    
    // view each individual error
    for _, e := range *err.(*sophos.Errors) {
    	e.Error() 
    	e.IsFatal()
    }
}

Generating Types

Sophos types are automatically generated using bin/gen.go which queries the UTM api/definitions path to generate all the files in the api which contain structs and helper functions corresponding to UTM API definitions.

Generated pacakages are versioned, feel free to generate against an older version and submit.

export ENDPOINT=192.168.0.1:4848
export TOKEN=abcde1234

make

Testing

make test

Todo

  • Create all unknown types (not returned from UTM) from their swagger definitions
  • Respond with Errors to ObjectClient functions for caller inspection
  • Finish adding all example from Sophos docs
  • Add nodes examples in README
  • Add PUT, POST, PATCH and DELETE methods to generated objects
  • Create a wrapper Client for REST objects client.Get(&nodes)

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

go-sophos's People

Contributors

esurdam avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.