README
¶
go-fmc
go-fmc is a Go client library for Cisco Secure FMC (Firewall Management Center). It is based on Nathan's excellent goaci module and features a simple, extensible API and advanced JSON manipulation.
Getting Started
Installing
To start using go-fmc, install Go and go get:
$ go get -u github.com/netascode/go-fmc
Basic Usage
package main
import "github.com/netascode/go-fmc"
func main() {
client, _ := fmc.NewClient("https://1.1.1.1", "user", "pwd")
res, _ := client.Get("/api/fmc_config/v1/domain/{DOMAIN_UUID}/object/networks")
println(res.Get("items.0.name").String())
}
This will print something like:
any-ipv4
Result manipulation
fmc.Result uses GJSON to simplify handling JSON results. See the GJSON documentation for more detail.
res, _ := client.Get("/api/fmc_config/v1/domain/{DOMAIN_UUID}/object/networks")
for _, obj := range res.Get("items").Array() {
println(obj.Get("@pretty").String()) // pretty print network objects
}
POST data creation
fmc.Body is a wrapper for SJSON. SJSON supports a path syntax simplifying JSON creation.
body := fmc.Body{}.
Set("name", "net1").
Set("value", "1.5.4.0/24")
client.Post("/api/fmc_config/v1/domain/{DOMAIN_UUID}/object/networks", body.Str)
Documentation
See the documentation for more details.
Documentation
¶
Overview ¶
Package fmc is a Cisco Secure FMC (Firewall Management Center) REST client library for Go.
Index ¶
- Constants
- func BackoffDelayFactor(x float64) func(*Client)
- func BackoffMaxDelay(x int) func(*Client)
- func BackoffMinDelay(x int) func(*Client)
- func CustomHttpClient(httpClient *http.Client) func(*Client)
- func DomainName(x string) func(*Req)
- func Insecure(x bool) func(*Client)
- func MaxRetries(x int) func(*Client)
- func NoLogPayload(req *Req)
- func RequestTimeout(x time.Duration) func(*Client)
- type Body
- type Client
- func (client *Client) Authenticate() error
- func (client *Client) Backoff(attempts int) bool
- func (client *Client) Delete(path string, mods ...func(*Req)) (Res, error)
- func (client *Client) Do(req Req) (Res, error)
- func (client *Client) Get(path string, mods ...func(*Req)) (Res, error)
- func (client *Client) GetFMCVersion() error
- func (client *Client) Login() error
- func (client Client) NewReq(method, uri string, body io.Reader, mods ...func(*Req)) (Req, error)
- func (client *Client) Post(path, data string, mods ...func(*Req)) (Res, error)
- func (client *Client) Put(path, data string, mods ...func(*Req)) (Res, error)
- func (client *Client) Refresh() error
- type Req
- type Res
Constants ¶
const DefaultBackoffDelayFactor float64 = 3
const DefaultBackoffMaxDelay int = 60
const DefaultBackoffMinDelay int = 2
const DefaultMaxRetries int = 3
Variables ¶
This section is empty.
Functions ¶
func BackoffDelayFactor ¶
BackoffDelayFactor modifies the backoff delay factor from the default of 3.
func BackoffMaxDelay ¶
BackoffMaxDelay modifies the maximum delay between two retries from the default of 60.
func BackoffMinDelay ¶
BackoffMinDelay modifies the minimum delay between two retries from the default of 2.
func CustomHttpClient ¶
Replace the default HTTP client with a custom one.
func DomainName ¶
DomainName modifies the domain to be used for the request.
func Insecure ¶
Insecure determines if insecure https connections are allowed. Default value is true.
func MaxRetries ¶
MaxRetries modifies the maximum number of retries from the default of 3.
func NoLogPayload ¶
func NoLogPayload(req *Req)
NoLogPayload prevents logging of payloads. Primarily used by the Login and Refresh methods where this could expose secrets.
func RequestTimeout ¶
RequestTimeout modifies the HTTP request timeout from the default of 60 seconds.
Types ¶
type Body ¶
type Body struct {
Str string
}
Body wraps SJSON for building JSON body strings. Usage example:
Body{}.Set("name", "ABC").Str
type Client ¶
type Client struct {
// HttpClient is the *http.Client used for API requests.
HttpClient *http.Client
// Url is the FMC IP or hostname, e.g. https://10.0.0.1:443 (port is optional).
Url string
// Authentication token is the current authentication token
AuthToken string
// Refresh token is the current authentication token
RefreshToken string
// Usr is the FMC username.
Usr string
// Pwd is the FMC password.
Pwd string
// Insecure determines if insecure https connections are allowed.
Insecure bool
// Maximum number of retries
MaxRetries int
// Minimum delay between two retries
BackoffMinDelay int
// Maximum delay between two retries
BackoffMaxDelay int
// Backoff delay factor
BackoffDelayFactor float64
// LastRefresh is the timestamp of the last authentication token refresh
LastRefresh time.Time
// RefreshCount is the number to authentication token refreshes with the same refresh token
RefreshCount int
// DomainUUID is the UUID of the global domain returned when generating a token
DomainUUID string
// Map of domain names to domain UUIDs
Domains map[string]string
// FMC Version
FMCVersion string
RateLimiterBucket *ratelimit.Bucket
// contains filtered or unexported fields
}
Client is an HTTP FMC client. Use fmc.NewClient to initiate a client. This will ensure proper cookie handling and processing of modifiers.
Requests are protected from concurrent writing (concurrent DELETE/POST/PUT), across all API paths. Any GET requests, or requests from different clients are not protected against concurrent writing.
func NewClient ¶
NewClient creates a new FMC HTTP client. Pass modifiers in to modify the behavior of the client, e.g.
client, _ := NewClient("fmc1.cisco.com", "user", "password", RequestTimeout(120))
func (*Client) Authenticate ¶
Login if no token available.
func (*Client) Do ¶
Do makes a request. Requests for Do are built ouside of the client, e.g.
req := client.NewReq("GET", "/api/fmc_config/v1/domain/{DOMAIN_UUID}/object/networks", nil)
res, _ := client.Do(req)
func (*Client) Get ¶
Get makes a GET requests and returns a GJSON result. It handles pagination and returns all items in a single response.
func (Client) NewReq ¶
NewReq creates a new Req request for this client. Use a "{DOMAIN_UUID}" placeholder in the URI to be replaced with the domain UUID.
func (*Client) Post ¶
Post makes a POST request and returns a GJSON result. Hint: Use the Body struct to easily create POST body data.
type Req ¶
type Req struct {
// HttpReq is the *http.Request obejct.
HttpReq *http.Request
// LogPayload indicates whether logging of payloads should be enabled.
LogPayload bool
// DomainName is the FMC domain to be used for the request.
DomainName string
}
Req wraps http.Request for API requests.
type Res ¶
Res is an API response returned by client requests. This is a GJSON result, which offers advanced and safe parsing capabilities. https://github.com/tidwall/gjson
Source Files