README
¶
go-fmc
go-fmc is a Go client library for Cisco Secure FMC (Firewall Management Center) and cdFMC (Cloud-Delivered FMC). 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
Self-managed FMC
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())
}
Cloud-managed FMC
package main
import "github.com/netascode/go-fmc"
func main() {
client, _ := fmc.NewClientCDFMC("https://<YOUR_TENNANT_URL>.cdo.cisco.com", "apiToken")
res, _ := client.Get("/api/fmc_config/v1/domain/{DOMAIN_UUID}/object/networks")
println(res.Get("items.0.name").String())
}
Output
Both of those examples 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 RequestID(x string) func(*Req)
- func RequestTimeout(x time.Duration) func(*Client)
- func UserAgent(x string) func(*Client)
- type Body
- type Client
- func (client *Client) AuthToken() string
- func (client *Client) Authenticate(currentAuthToken string) 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) 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)
- 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
// UserAgent is the HTTP User-Agent string
UserAgent string
// Usr is the FMC username. Not used for cdFMC.
Usr string
// Pwd is the FMC password or cdFMC API token
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 user login domain.
DomainUUID string
// Map of domain names to domain UUIDs.
Domains map[string]string
// FMC Version string as returned by FMC - ex. 7.7.0 (build 91)
FMCVersion string
// FMC Version parsed to go-version library - ex. 7.7.0
FMCVersionParsed *version.Version
// Is this cdFMC connection
IsCDFMC bool
// Rate limit requests to FMC
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 NewClientCDFMC ¶ added in v0.2.0
Create a new cdFMC HTTP client.
func (*Client) Authenticate ¶
Authenticate assures the token is there and valid. It will try to login/refresh the token based on the current state and information from FMC on failures (no proactive reauthentications). currentAuthToken is the token used in the request. This helps to determine, if authToken needs refreshing or has already been refreshed by other thread. currentAuthToken can be an empty string.
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.
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
// ID for the request.
RequestID 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