pango

README

Palo Alto Networks pango

Package pango is a golang cross version mechanism for interacting with Palo Alto Networks devices (including physical and virtualized Next-generation Firewalls and Panorama). Versioning support is in place for PANOS 6.1 to 10.0.

Please refer to the godoc reference documentation above to get started.

Using pango

To start, create a client connection with the desired parameters and then initialize the connection:

package main

import (
    "log"
    "github.com/PaloAltoNetworks/pango"
)

func main() {
    var err error

    c := &pango.Firewall{Client: pango.Client{
        Hostname: "127.0.0.1",
        Username: "admin",
        Password: "admin",
        Logging: pango.LogAction | pango.LogOp,
    }}
    if err = c.Initialize(); err != nil {
        log.Printf("Failed to initialize client: %s", err)
        return
    }
    log.Printf("Initialize ok")
}

Initializing the connection creates the API key (if it was not already specified), then performs show system info to get the PANOS version. Once the firewall client connection is created, you can query and configure the Palo Alto Networks device from the functions inside the various namespaces of the client connection. Namespaces correspond to the various configuration areas available in the GUI. For example:

    err = c.Network.EthernetInterface.Set(...)
    myPolicies, err := c.Policies.Security.GetList()

Generally speaking, there are the following functions inside each namespace:

• Get() / GetList() / GetAll()
• Show() / ShowList() / ShowAll()
• Set()
• Edit()
• Delete()

These functions correspond with PANOS Get, Show, Set, Edit, and Delete API calls. Get(), Set(), and Edit() take and return normalized, version independent objects. These version safe objects are typically named Entry, which corresponds to how the object is placed in the PANOS XPATH.

Some Entry objects have a special function, Defaults(). Invoking this function will initialize the object with some default values. Each Entry that implements Defaults() calls out in its documentation what parameters are affected by this, and what the defaults are.

For any version safe object, attempting to configure a parameter that your PANOS doesn't support will be safely ignored in the resultant XML sent to the firewall / Panorama.

Using Edit Functions

The PANOS XML API Edit command can be used to both create as well as update existing config, however it can also truncate config for the given XPATH. Due to this, if you want to use Edit(), you need to make sure that you perform either a Get() or a Show() first, make your modification, then invoke Edit() using that object. If you don't do this, you will truncate any sub config.

Documentation

Overview

Package pango is a golang cross version mechanism for interacting with Palo Alto Networks devices (including physical and virtualized Next-generation Firewalls and Panorama). Versioning support is in place for PAN-OS 6.1 and up.

To start, create a client connection with the desired parameters and then initialize the connection:

package main

import (
    "log"
    "github.com/PaloAltoNetworks/pango"
)

func main() {
    var err error
    c := pango.Firewall{Client: pango.Client{
        Hostname: "127.0.0.1",
        Username: "admin",
        Password: "admin",
        Logging: pango.LogAction | pango.LogOp,
    }}
    if err = c.Initialize(); err != nil {
        log.Printf("Failed to initialize client: %s", err)
        return
    }
    log.Printf("Initialize ok")
}

Initializing the connection creates the API key (if it was not already specified), then performs "show system info" to get the PAN-OS version. Once the firewall client is created, you can query and configure the Palo Alto Networks device from the functions inside the various namespaces of the client connection. Namespaces correspond to the various configuration areas available in the GUI. For example:

err = c.Network.EthernetInterface.Set(...)
myPolicies, err := c.Policies.Security.GetList(...)

Generally speaking, there are the following functions inside each namespace:

• Get / GetList / GetAll
• Show / ShowList / ShowAll
• Set
• Edit
• Delete

These functions correspond with PAN-OS Get, Show, Set, Edit, and Delete API calls. Get(), Set(), and Edit() take and return normalized, version independent objects. These version safe objects are typically named Entry, which corresponds to how the object is placed in the PAN-OS XPATH.

Some Entry objects have a special function, Defaults(). Invoking this function will initialize the object with some default values. Each Entry that implements Defaults() calls out in its documentation what parameters are affected by this, and what the defaults are.

For any version safe object, attempting to configure a parameter that your PAN-OS doesn't support will be safely ignored in the resultant XML sent to the firewall / Panorama.

Loading PAN-OS Config

A PAN-OS configuration can be loaded from a PAN-OS device using `RetrievePanosConfig()` to pull it from a live device or `LoadPanosConfig()` if already in local memory. Once it's been loaded, use `FromPanosConfig()` for singletons and `AllFromPanosConfig()` for slices of normalized objects from the loaded config.

You can also use this file load and config retrieval to do offline inspection of the config, just make sure to set `pango.Client.Version` to the appropriate PAN-OS version so the version normalization can take place.

Using Edit Functions

The PAN-OS XML API Edit command can be used to both create as well as update existing config, however it can also truncate config for the given XPATH. Due to this, if you want to use Edit(), you need to make sure that you perform either a Get() or a Show() first, make your modification, then invoke Edit() using that object. If you don't do this, you will truncate any sub config.

To learn more about PAN-OS XML API, please refer to the Palo Alto Netowrks API documentation.

XPATHs

Functions such as `panos.Client.Set`, `panos.Client.Edit`, and `panos.Client.Delete` take a parameter named `path`. This path can be either a fully formed XPATH as a string or a list of strings such as `[]string{"config", "shared", "address"}`. The grand majority of namespaces give their paths as a list of strings, as the XPATH oftentimes needs to be tweaked depending on SET vs EDIT, single objects vs multiple objects, etc, so handling path updates is easier this way.

Example (CreateAddressGroup)

Example_createAddressGroup is a Panorama example on how to create/delete a security policy with the associated address group and addresses

package main

import (
	"log"

	"github.com/PaloAltoNetworks/pango"
	"github.com/PaloAltoNetworks/pango/commit"
	"github.com/PaloAltoNetworks/pango/objs/addr"
	"github.com/PaloAltoNetworks/pango/objs/addrgrp"
	"github.com/PaloAltoNetworks/pango/poli/security"
	"github.com/PaloAltoNetworks/pango/util"
)

func main() {
	var deviceGroup = "MyDeviceGroup"
	var tags = []string{"sometag"}
	var err error

	pan := &pango.Panorama{Client: pango.Client{
		Hostname: "192.168.1.1",
		Username: "admin",
		Password: "admin",
		Logging:  pango.LogAction | pango.LogOp,
	}}
	if err = pan.Initialize(); err != nil {
		log.Panic(err)
		return
	}

	// Create the addresses, address group and security policy
	addr1 := addr.Entry{
		Name:        "SampleAddress1",
		Value:       "10.192.226.101/32",
		Type:        addr.IpNetmask,
		Description: "First address of a sample address group",
		Tags:        tags,
	}
	if err = pan.Objects.Address.Set(deviceGroup, addr1); err != nil {
		log.Panic(err)
	}

	addr2 := addr.Entry{
		Name:        "SampleAddress2",
		Value:       "10.192.226.102/32",
		Type:        addr.IpNetmask,
		Description: "Second address of a sample address group",
		Tags:        tags,
	}
	if err = pan.Objects.Address.Set(deviceGroup, addr2); err != nil {
		log.Panic(err)
	}

	ag := addrgrp.Entry{
		Name:            "SampleAddressGroup",
		Description:     "This in an example on how to use address groups",
		StaticAddresses: []string{addr1.Name, addr2.Name},
		Tags:            tags,
	}
	if err = pan.Objects.AddressGroup.Set(deviceGroup, ag); err != nil {
		log.Panic(err)
	}

	securityPolicy := security.Entry{
		Name:                 "SamplePolicy",
		Description:          "This is where the request number goes",
		Tags:                 tags,
		SourceZones:          []string{"CORPEXT"},
		SourceAddresses:      []string{"any"},
		DestinationZones:     []string{"CORPDMZ"},
		DestinationAddresses: []string{ag.Name},
		Applications:         []string{"ssl"},
		Services:             []string{"application-default"},
		LogSetting:           "Standard-Logging",
		Group:                "Corp_Default",
	}
	securityPolicy.Defaults()

	if err = pan.Policies.Security.VerifiableSet(deviceGroup, util.PreRulebase, securityPolicy); err != nil {
		log.Panic(err)
	}

	panCommit := commit.PanoramaCommit{
		Description:  "Created example address group",
		Admins:       nil,
		DeviceGroups: []string{deviceGroup},
	}

	resp, bytes, err := pan.Commit(panCommit, "", nil)
	if err != nil {
		log.Panic(err)
	}
	log.Printf("Job ID: %v\n", resp)
	log.Printf("Response XML: %v\n", string(bytes))

	// Delete the addresses, address group and security policy
	// Note that the Delete function can take their respective enty structs, or just a string with the name as shown below
	if err = pan.Policies.Security.Delete(deviceGroup, util.PreRulebase, securityPolicy.Name); err != nil {
		log.Panic(err)
	}
	if err = pan.Objects.AddressGroup.Delete(deviceGroup, ag.Name); err != nil {
		log.Panic(err)
	}
	if err = pan.Objects.Address.Delete(deviceGroup, addr1.Name); err != nil {
		log.Panic(err)
	}
	if err = pan.Objects.Address.Delete(deviceGroup, addr2.Name); err != nil {
		log.Panic(err)
	}

	panCommit = commit.PanoramaCommit{
		Description:  "Deleted sample address group",
		Admins:       nil,
		DeviceGroups: []string{deviceGroup},
	}

	resp, bytes, err = pan.Commit(panCommit, "", nil)
	if err != nil {
		log.Panic(err)
	}
	log.Printf("Job ID: %v\n", resp)
	log.Printf("Response XML: %v\n", string(bytes))

}

Example (CreateInterface)

ExampleCreateInterface demonstrates how to use pango to create an interface if the interface is not already configured.

package main

import (
	"log"

	"github.com/PaloAltoNetworks/pango"
	"github.com/PaloAltoNetworks/pango/netw/interface/eth"
)

func main() {
	var err error

	// Connect to the firewall.
	fw := pango.Firewall{Client: pango.Client{
		Hostname: "192.168.1.1",
		Username: "admin",
		Password: "admin",
	}}

	// Connect to the firewall and verify authentication params.
	if err = fw.Initialize(); err != nil {
		log.Fatalf("Failed to connect to %s: %s", fw.Hostname, err)
	}

	// Define the ethernet interface we want to configure.
	e := eth.Entry{
		Name:      "ethernet1/7",
		Mode:      "layer3",
		Comment:   "Made by pango",
		StaticIps: []string{"10.1.1.1/24", "10.2.1.1/24"},
	}

	// If the interface is already present, leave it alone.
	ethList, err := fw.Network.EthernetInterface.GetList()
	if err != nil {
		log.Fatalf("Failed to get interface listing: %s", err)
	}
	for i := range ethList {
		if ethList[i] == e.Name {
			log.Printf("Interface %q already exists, quitting.", e.Name)
			return
		}
	}

	// Since the interface is not present, configure it.
	if err = fw.Network.EthernetInterface.Set("vsys1", e); err != nil {
		log.Fatalf("Failed to create %q: %s", e.Name, err)
	}
	log.Printf("Created %q ok", e.Name)
}

Example (FirewallCommit)

package main

import (
	"flag"
	"log"
	"strings"
	"time"

	"github.com/PaloAltoNetworks/pango"
	"github.com/PaloAltoNetworks/pango/commit"
)

func main() {
	var (
		err                                                      error
		configFile, hostname, username, password, apiKey, admins string
		edan, eso, epao, force                                   bool
		jobId                                                    uint
		sleep                                                    int64
		timeout                                                  int
	)

	log.SetFlags(log.Ldate | log.Ltime | log.Lmicroseconds)

	flag.StringVar(&configFile, "config", "", "JSON config file with panos connection info")
	flag.StringVar(&hostname, "host", "", "PAN-OS hostname")
	flag.StringVar(&username, "user", "", "PAN-OS username")
	flag.StringVar(&password, "pass", "", "PAN-OS password")
	flag.StringVar(&apiKey, "key", "", "PAN-OS API key")
	flag.StringVar(&admins, "admins", "", "CSV of specific admins for partial config commit")
	flag.BoolVar(&edan, "exclude-device-and-network", false, "Exclude device and network")
	flag.BoolVar(&eso, "exclude-shared-objects", false, "Exclude shared objects")
	flag.BoolVar(&epao, "exclude-policy-and-objects", false, "Exclude policy and objects")
	flag.BoolVar(&force, "force", false, "Force a commit even if one isn't needed")
	flag.Int64Var(&sleep, "sleep", 0, "Seconds to sleep between checks for commit completion")
	flag.IntVar(&timeout, "timeout", 10, "The timeout for all PAN-OS API calls")
	flag.Parse()

	// Connect to the firewall.
	fw := &pango.Firewall{Client: pango.Client{
		Hostname: hostname,
		Username: username,
		Password: password,
		ApiKey:   apiKey,
		Logging:  pango.LogOp | pango.LogAction,
		Timeout:  timeout,
	}}
	if err = fw.InitializeUsing(configFile, true); err != nil {
		log.Fatalf("Failed: %s", err)
	}

	// Build the commit to be performed.
	cmd := commit.FirewallCommit{
		Description:             flag.Arg(0),
		ExcludeDeviceAndNetwork: edan,
		ExcludeSharedObjects:    eso,
		ExcludePolicyAndObjects: epao,
		Force:                   force,
	}
	admins = strings.TrimSpace(admins)
	if admins != "" {
		cmd.Admins = strings.Split(admins, ",")
	}

	sd := time.Duration(sleep) * time.Second

	// Perform the commit
	jobId, _, err = fw.Commit(cmd, "", nil)
	if err != nil {
		log.Fatalf("Error in commit: %s", err)
	} else if jobId == 0 {
		log.Printf("No commit needed")
	} else if err = fw.WaitForJob(jobId, sd, nil, nil); err != nil {
		log.Printf("Error in commit: %s", err)
	} else {
		log.Printf("Committed config successfully")
	}
}

Example (OutputApiKey)

ExamplePanosInfo outputs various info about a PAN-OS device as JSON.

package main

import (
	"encoding/json"
	"fmt"

	"github.com/PaloAltoNetworks/pango"
)

// About is a struct to hold information about the given PAN-OS device.
type About struct {
	Hostname string `json:"hostname"`
	Type     string `json:"type"`
	Model    string `json:"model"`
	Version  string `json:"version"`
	Serial   string `json:"serial"`
}

// ExamplePanosInfo outputs various info about a PAN-OS device as
// JSON.
func main() {
	var out About

	conInfo := pango.Client{
		Hostname: "192.168.1.1",
		Username: "admin",
		Password: "admin",
		Logging:  pango.LogQuiet,
	}

	con, err := pango.Connect(conInfo)
	if err != nil {
		return
	}

	switch x := con.(type) {
	case *pango.Firewall:
		out = About{
			Hostname: x.Hostname,
			Type:     "NGFW",
			Model:    x.SystemInfo["model"],
			Version:  x.Version.String(),
			Serial:   x.SystemInfo["serial"],
		}
	case *pango.Panorama:
		out = About{
			Hostname: x.Hostname,
			Type:     "Panorama",
			Model:    x.SystemInfo["model"],
			Version:  x.Version.String(),
			Serial:   x.SystemInfo["serial"],
		}
	}

	b, err := json.Marshal(out)
	if err != nil {
		return
	}

	fmt.Printf("%s\n", b)
}

Index

• Constants
• func Connect(c Client) (interface{}, error)
• func ConnectUsing(c Client, filename string, chkenv bool) (interface{}, error)
• type Client
  • func (c *Client) Clock() (time.Time, error)
  • func (c *Client) Commit(cmd interface{}, action string, extras interface{}) (uint, []byte, error)
  • func (c *Client) CommitLocks(vsys string) ([]util.Lock, error)
  • func (c *Client) Communicate(data url.Values, ans interface{}) ([]byte, http.Header, error)
  • func (c *Client) CommunicateFile(content, filename, fp string, data url.Values, ans interface{}) ([]byte, http.Header, error)
  • func (c *Client) ConfigLocks(vsys string) ([]util.Lock, error)
  • func (c *Client) ConfigTree() *util.XmlNode
  • func (c *Client) Delete(path, extras, ans interface{}) ([]byte, error)
  • func (c *Client) Edit(path, element, extras, ans interface{}) ([]byte, error)
  • func (c *Client) EntryListUsing(fn util.Retriever, path []string) ([]string, error)
  • func (c *Client) Export(category string, timeout time.Duration, extras, ans interface{}) (string, []byte, error)
  • func (c *Client) Get(path, extras, ans interface{}) ([]byte, error)
  • func (c *Client) GetTechSupportFile(timeout time.Duration) (string, []byte, error)
  • func (c *Client) Import(cat, content, filename, fp string, timeout time.Duration, ...) ([]byte, error)
  • func (c *Client) Initialize() error
  • func (c *Client) InitializeUsing(filename string, chkenv bool) error
  • func (c *Client) IsImported(loc, tmpl, ts, vsys, name string) (bool, error)
  • func (c *Client) LoadPanosConfig(config []byte) error
  • func (c *Client) LockCommits(vsys, comment string) error
  • func (c *Client) LockConfig(vsys, comment string) error
  • func (c *Client) Log(logType, action, query, dir string, nlogs, skip int, extras, ans interface{}) ([]byte, error)
  • func (c *Client) LogAction(msg string, i ...interface{})
  • func (c *Client) LogExport(msg string, i ...interface{})
  • func (c *Client) LogImport(msg string, i ...interface{})
  • func (c *Client) LogLog(msg string, i ...interface{})
  • func (c *Client) LogOp(msg string, i ...interface{})
  • func (c *Client) LogQuery(msg string, i ...interface{})
  • func (c *Client) LogUid(msg string, i ...interface{})
  • func (c *Client) MemberListUsing(fn util.Retriever, path []string) ([]string, error)
  • func (c *Client) Move(path interface{}, where, dst string, extras, ans interface{}) ([]byte, error)
  • func (c *Client) MultiConfig(element MultiConfigure, strict bool, extras interface{}) ([]byte, MultiConfigureResponse, error)
  • func (c *Client) Op(req interface{}, vsys string, extras, ans interface{}) ([]byte, error)
  • func (c *Client) Plugins() []plugin.Info
  • func (c *Client) PositionFirstEntity(mvt int, rel, ent string, path, elms []string) error
  • func (c *Client) PrepareMultiConfigure(capacity int)
  • func (c *Client) Rename(path interface{}, newname string, extras, ans interface{}) ([]byte, error)
  • func (c *Client) RequestPasswordHash(val string) (string, error)
  • func (c *Client) RetrieveApiKey() error
  • func (c *Client) RetrievePanosConfig(value string) error
  • func (c *Client) RevertToRunningConfig() error
  • func (c *Client) SendMultiConfigure(strict bool) (MultiConfigureResponse, error)
  • func (c *Client) Set(path, element, extras, ans interface{}) ([]byte, error)
  • func (c *Client) Show(path, extras, ans interface{}) ([]byte, error)
  • func (c *Client) String() string
  • func (c *Client) Uid(cmd interface{}, vsys string, extras, ans interface{}) ([]byte, error)
  • func (c *Client) UnlockCommits(vsys, admin string) error
  • func (c *Client) UnlockConfig(vsys string) error
  • func (c *Client) ValidateConfig(sync bool, sleep time.Duration) (uint, error)
  • func (c *Client) Versioning() version.Number
  • func (c *Client) VsysImport(loc, tmpl, ts, vsys string, names []string) error
  • func (c *Client) VsysUnimport(loc, tmpl, ts string, names []string) error
  • func (c *Client) WaitForJob(id uint, sleep time.Duration, extras, resp interface{}) error
  • func (c *Client) WaitForLogs(id uint, sleep, timeout time.Duration, ans interface{}) ([]byte, error)
• type Firewall
  • func (c *Firewall) GetDhcpInfo(i string) (map[string]string, error)
  • func (c *Firewall) Initialize() error
  • func (c *Firewall) InitializeUsing(filename string, chkenv bool) error
• type McreMsg
• type MultiConfigResponseElement
  • func (m *MultiConfigResponseElement) Message() string
  • func (m *MultiConfigResponseElement) Ok() bool
• type MultiConfigure
  • func (m *MultiConfigure) IncrementalIds()
• type MultiConfigureRequest
• type MultiConfigureResponse
  • func (m *MultiConfigureResponse) Error() string
  • func (m *MultiConfigureResponse) Ok() bool
• type Panorama
  • func (c *Panorama) CreateVmAuthKey(hours int) (VmAuthKey, error)
  • func (c *Panorama) GetVmAuthKeys() ([]VmAuthKey, error)
  • func (c *Panorama) Initialize() error
  • func (c *Panorama) InitializeUsing(filename string, chkenv bool) error
  • func (c *Panorama) RevokeVmAuthKey(key string) error
• type VmAuthKey
  • func (o *VmAuthKey) ParseExpires(clock time.Time)

Examples

• Package (CreateAddressGroup)
• Package (CreateInterface)
• Package (FirewallCommit)
• Package (OutputApiKey)

Constants

const (
	LogQuiet = 1 << (iota + 1)
	LogAction
	LogQuery
	LogOp
	LogUid
	LogLog
	LogExport
	LogImport
	LogXpath
	LogSend
	LogReceive
	LogOsxCurl
	LogCurlWithPersonalData
)

These bit flags control what is logged by client connections. Of the flags available for use, LogSend and LogReceive will log ALL communication between the connection object and the PAN-OS XML API. The API key being used for communication will be blanked out, but no other sensitive data will be. As such, those two flags should be considered for debugging only. To disable all logging, set the logging level as LogQuiet.

As of right now, pango is not officially supported by Palo Alto Networks TAC, however using the API itself via cURL is. If you run into an issue and you believe it to be a PAN-OS problem, you can enable a cURL output logging style to have pango output an equivalent cURL command to use when interfacing with TAC.

If you want to get the cURL command so that you can run it yourself, then set the LogCurlWithPersonalData flag, which will output your real API key, hostname, and any custom headers you have configured the client to send to PAN-OS.

The bit-wise flags are as follows:

• LogQuiet: disables all logging
• LogAction: action being performed (Set / Edit / Delete functions)
• LogQuery: queries being run (Get / Show functions)
• LogOp: operation commands (Op functions)
• LogUid: User-Id commands (Uid functions)
• LogLog: log retrieval commands
• LogExport: log export commands
• LogXpath: the resultant xpath
• LogSend: xml docuemnt being sent
• LogReceive: xml responses being received
• LogOsxCurl: output an OSX cURL command for the data being sent in
• LogCurlWithPersonalData: If doing a curl style logging, then include personal data in the curl command instead of tokens.

Functions

func Connect

func Connect(c Client) (interface{}, error)

Connect opens a connection to the PAN-OS client, then uses the "model" info to return a pointer to either a Firewall or Panorama struct.

The Initialize function is invoked as part of this discovery, so there is no need to Initialize() the Client connection prior to invoking this.

func ConnectUsing

func ConnectUsing(c Client, filename string, chkenv bool) (interface{}, error)

ConnectUsing does Connect(), but takes in a filename that contains fallback authentication credentials if they aren't specified.

The order of preference for auth / connection settings is:

* explicitly set * environment variable (set chkenv to true to enable this) * json file

Types

type Client

type Client struct {
	// Connection properties.
	Hostname string            `json:"hostname"`
	Username string            `json:"username"`
	Password string            `json:"password"`
	ApiKey   string            `json:"api_key"`
	Protocol string            `json:"protocol"`
	Port     uint              `json:"port"`
	Timeout  int               `json:"timeout"`
	Target   string            `json:"target"`
	Headers  map[string]string `json:"headers"`

	// Set to true if you want to check environment variables
	// for auth and connection properties.
	CheckEnvironment bool `json:"-"`

	// HTTP transport options.  Note that the VerifyCertificate setting is
	// only used if you do not specify a HTTP transport yourself.
	VerifyCertificate bool            `json:"verify_certificate"`
	Transport         *http.Transport `json:"-"`

	// Variables determined at runtime.
	Version        version.Number    `json:"-"`
	SystemInfo     map[string]string `json:"-"`
	Plugin         []plugin.Info     `json:"-"`
	MultiConfigure *MultiConfigure   `json:"-"`

	// Logging level.
	Logging               uint32   `json:"-"`
	LoggingFromInitialize []string `json:"logging"`
	// contains filtered or unexported fields
}

Client is a generic connector struct. It provides wrapper functions for invoking the various PAN-OS XPath API methods. After creating the client, invoke Initialize() to prepare it for use.

Many of the functions attached to this struct will take a param named `extras`. Under normal circumstances this will just be nil, but if you have some extra values you need to send in with your request you can specify them here.

Likewise, a lot of these functions will return a slice of bytes. Under normal circumstances, you don't need to do anything with this, but sometimes you do, so you can find the raw XML returned from PAN-OS there.

func (*Client) Clock

func (c *Client) Clock() (time.Time, error)

Clock gets the time on the PAN-OS appliance.

func (*Client) Commit

func (c *Client) Commit(cmd interface{}, action string, extras interface{}) (uint, []byte, error)

Commit performs PAN-OS commits.

The cmd param can be a properly formatted XML string, a struct that can be marshalled into XML, or one of the commit types that can be found in the commit package.

The action param is the commit action to be taken. If you are using one of the commit structs as the `cmd` param and the action param is an empty string, then the action is taken from the commit struct passed in.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

Commits result in a job being submitted to the backend. The job ID, assuming the commit action was successfully submitted, the response from the server, and if an error was encountered or not are all returned from this function.

func (*Client) CommitLocks

func (c *Client) CommitLocks(vsys string) ([]util.Lock, error)

CommitLocks returns any commit locks that are currently in place.

If vsys is an empty string, then the vsys will default to "shared".

func (*Client) Communicate

func (c *Client) Communicate(data url.Values, ans interface{}) ([]byte, http.Header, error)

Communicate sends the given data to PAN-OS.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

Even if an answer struct is given, we first check for known error formats. If a known error format is detected, unmarshalling into the answer struct is not performed.

If the API key is set, but not present in the given data, then it is added in.

func (*Client) CommunicateFile

func (c *Client) CommunicateFile(content, filename, fp string, data url.Values, ans interface{}) ([]byte, http.Header, error)

CommunicateFile does a file upload to PAN-OS.

The content param is the content of the file you want to upload.

The filename param is the basename of the file you want to specify in the multipart form upload.

The fp param is the name of the param for the file upload.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

Even if an answer struct is given, we first check for known error formats. If a known error format is detected, unmarshalling into the answer struct is not performed.

If the API key is set, but not present in the given data, then it is added in.

func (*Client) ConfigLocks

func (c *Client) ConfigLocks(vsys string) ([]util.Lock, error)

ConfigLocks returns any config locks that are currently in place.

If vsys is an empty string, then the vsys will default to "shared".

func (*Client) ConfigTree

func (c *Client) ConfigTree() *util.XmlNode

ConfigTree returns the configuration tree that was loaded either via `RetrievePanosConfig()` or `LoadPanosConfig()`.

func (*Client) Delete

func (c *Client) Delete(path, extras, ans interface{}) ([]byte, error)

Delete runs a "delete" type command, removing the supplied xpath and everything underneath it.

The path param should be either a string or a slice of strings.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) Edit

func (c *Client) Edit(path, element, extras, ans interface{}) ([]byte, error)

Edit runs a "edit" type command, modifying what is at the given xpath with the supplied element.

The path param should be either a string or a slice of strings.

The element param can be either a string of properly formatted XML to send or a struct which can be marshaled into a string.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) EntryListUsing

func (c *Client) EntryListUsing(fn util.Retriever, path []string) ([]string, error)

EntryListUsing retrieves an list of entries using the given function, either Get or Show.

func (*Client) Export

func (c *Client) Export(category string, timeout time.Duration, extras, ans interface{}) (string, []byte, error)

Export runs an "export" type command.

The category param specifies the desired file type to export.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

If the export invoked results in a file being downloaded from PAN-OS, then the string returned is the name of the remote file that is retrieved, otherwise it's just an empty string.

func (*Client) Get

func (c *Client) Get(path, extras, ans interface{}) ([]byte, error)

Get runs a "get" type command.

The path param should be either a string or a slice of strings.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) GetTechSupportFile

func (c *Client) GetTechSupportFile(timeout time.Duration) (string, []byte, error)

GetTechSupportFile returns the tech support .tgz file.

This function returns the name of the tech support file, the file contents, and an error if one occurred.

The timeout param is the new timeout (in seconds) to temporarily assign to client connections to allow for the successful download of the tech support file. If the timeout is zero, then pango.Client.Timeout is the timeout for tech support file retrieval.

func (*Client) Import

func (c *Client) Import(cat, content, filename, fp string, timeout time.Duration, extras, ans interface{}) ([]byte, error)

Import performs an import type command.

The cat param is the category.

The content param is the content of the file you want to upload.

The filename param is the basename of the file you want to specify in the multipart form upload.

The fp param is the name of the param for the file upload.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) Initialize

func (c *Client) Initialize() error

Initialize does some initial setup of the Client connection, retrieves the API key if it was not already present, then performs "show system info" to get the PAN-OS version. The full results are saved into the client's SystemInfo map.

If not specified, the following is assumed:

• Protocol: https
• Port: (unspecified)
• Timeout: 10
• Logging: LogAction | LogUid

func (*Client) InitializeUsing

func (c *Client) InitializeUsing(filename string, chkenv bool) error

InitializeUsing does Initialize(), but takes in a filename that contains fallback authentication credentials if they aren't specified.

The order of preference for auth / connection settings is:

* explicitly set * environment variable (set chkenv to true to enable this) * json file

func (*Client) IsImported

func (c *Client) IsImported(loc, tmpl, ts, vsys, name string) (bool, error)

IsImported checks if the importable object is actually imported in the specified location.

func (*Client) LoadPanosConfig

func (c *Client) LoadPanosConfig(config []byte) error

LoadPanosConfig stores the given XML document into the local client instance.

The `config` can either be `<config>...</config>` or something that contians only the config document (such as `<result ...><config>...</config></result>`).

After the config is loaded, config can be queried and retrieved using any `FromPanosConfig()` methods.

func (*Client) LockCommits

func (c *Client) LockCommits(vsys, comment string) error

LockCommits locks commits for the given scope with the given comment.

If vsys is an empty string, the scope defaults to "shared".

func (*Client) LockConfig

func (c *Client) LockConfig(vsys, comment string) error

LockConfig locks the config for the given scope with the given comment.

If vsys is an empty string, the scope defaults to "shared".

func (*Client) Log

func (c *Client) Log(logType, action, query, dir string, nlogs, skip int, extras, ans interface{}) ([]byte, error)

Log submits a "log" command.

Use `WaitForLogs` to get the results of the log command.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

Any response received from the server is returned, along with any errors encountered.

func (*Client) LogAction

func (c *Client) LogAction(msg string, i ...interface{})

LogAction writes a log message for SET/EDIT/DELETE operations if LogAction is set.

func (*Client) LogExport

func (c *Client) LogExport(msg string, i ...interface{})

LogExport writes a log message for EXPORT operations if LogExport is set.

func (*Client) LogImport

func (c *Client) LogImport(msg string, i ...interface{})

LogImport writes a log message for IMPORT operations if LogImport is set.

func (*Client) LogLog

func (c *Client) LogLog(msg string, i ...interface{})

LogLog writes a log message for LOG operations if LogLog is set.

func (*Client) LogOp

func (c *Client) LogOp(msg string, i ...interface{})

LogOp writes a log message for OP operations if LogOp is set.

func (*Client) LogQuery

func (c *Client) LogQuery(msg string, i ...interface{})

LogQuery writes a log message for GET/SHOW operations if LogQuery is set.

func (*Client) LogUid

func (c *Client) LogUid(msg string, i ...interface{})

LogUid writes a log message for User-Id operations if LogUid is set.

func (*Client) MemberListUsing

func (c *Client) MemberListUsing(fn util.Retriever, path []string) ([]string, error)

MemberListUsing retrieves an list of members using the given function, either Get or Show.

func (*Client) Move

func (c *Client) Move(path interface{}, where, dst string, extras, ans interface{}) ([]byte, error)

Move does a "move" type command.

func (*Client) MultiConfig

func (c *Client) MultiConfig(element MultiConfigure, strict bool, extras interface{}) ([]byte, MultiConfigureResponse, error)

MultiConfig does a "multi-config" type command.

Param strict should be true if you want strict transactional support.

Note that the error returned from this function is only if there was an error unmarshaling the response into the the multi config response struct. If the multi config itself failed, then the reason can be found in its results.

func (*Client) Op

func (c *Client) Op(req interface{}, vsys string, extras, ans interface{}) ([]byte, error)

Op runs an operational or "op" type command.

The req param can be either a properly formatted XML string or a struct that can be marshalled into XML.

The vsys param is the vsys the op command should be executed in, if any.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) Plugins

func (c *Client) Plugins() []plugin.Info

Plugins returns the plugin information.

func (*Client) PositionFirstEntity

func (c *Client) PositionFirstEntity(mvt int, rel, ent string, path, elms []string) error

PositionFirstEntity moves an element before another one using the Move API command.

Param `mvt` is a util.Move* constant.

Param `rel` is the relative entity that `mvt` is in relation to.

Param `ent` is the entity that is to be positioned.

Param `path` is the XPATH of `ent`.

Param `elms` is the ordered list of entities that should include both `rel` and `ent`. be found.

func (*Client) PrepareMultiConfigure

func (c *Client) PrepareMultiConfigure(capacity int)

PrepareMultiConfigure will start a multi config command.

Capacity is the initial capacity of the requests to be sent.

func (*Client) Rename

func (c *Client) Rename(path interface{}, newname string, extras, ans interface{}) ([]byte, error)

Rename does a "rename" type command.

func (*Client) RequestPasswordHash

func (c *Client) RequestPasswordHash(val string) (string, error)

RequestPasswordHash requests a password hash of the given string.

func (*Client) RetrieveApiKey

func (c *Client) RetrieveApiKey() error

RetrieveApiKey retrieves the API key, which will require that both the username and password are defined.

The currently set ApiKey is forgotten when invoking this function.

func (*Client) RetrievePanosConfig

func (c *Client) RetrievePanosConfig(value string) error

RetrievePanosConfig retrieves either the running config, candidate config, or the specified saved config file, then does `LoadPanosConfig()` to save it.

After the config is loaded, config can be queried and retrieved using any `FromPanosConfig()` methods.

Param `value` can be the word "candidate" to load candidate config or `running` to load running config. If the value is neither of those, it is assumed to be the name of a saved config and that is loaded.

func (*Client) RevertToRunningConfig

func (c *Client) RevertToRunningConfig() error

RevertToRunningConfig discards any changes made and reverts to the last config committed.

func (*Client) SendMultiConfigure

func (c *Client) SendMultiConfigure(strict bool) (MultiConfigureResponse, error)

SendMultiConfigure will send the accumulated multi configure request.

Param strict should be true if you want strict transactional support.

Note that the error returned from this function is only if there was an error unmarshaling the response into the the multi config response struct. If the multi config itself failed, then the reason can be found in its results.

func (*Client) Set

func (c *Client) Set(path, element, extras, ans interface{}) ([]byte, error)

Set runs a "set" type command, creating the element at the given xpath.

The path param should be either a string or a slice of strings.

The element param can be either a string of properly formatted XML to send or a struct which can be marshaled into a string.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) Show

func (c *Client) Show(path, extras, ans interface{}) ([]byte, error)

Show runs a "show" type command.

The path param should be either a string or a slice of strings.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

func (*Client) String

func (c *Client) String() string

String is the string representation of a client connection. Both the password and API key are replaced with stars, if set, making it safe to print the client connection in log messages.

func (*Client) Uid

func (c *Client) Uid(cmd interface{}, vsys string, extras, ans interface{}) ([]byte, error)

Uid performs User-ID API calls.

func (*Client) UnlockCommits

func (c *Client) UnlockCommits(vsys, admin string) error

UnlockCommits removes the commit lock on the given scope owned by the given admin, if this admin is someone other than the current acting admin.

If vsys is an empty string, the scope defaults to "shared".

func (*Client) UnlockConfig

func (c *Client) UnlockConfig(vsys string) error

UnlockConfig removes the config lock on the given scope.

If vsys is an empty string, the scope defaults to "shared".

func (*Client) ValidateConfig

func (c *Client) ValidateConfig(sync bool, sleep time.Duration) (uint, error)

ValidateConfig performs a commit config validation check.

Setting sync to true means that this function will block until the job finishes.

The sleep param is an optional sleep duration to wait between polling for job completion. This param is only used if sync is set to true.

This function returns the job ID and if any errors were encountered.

func (*Client) Versioning

func (c *Client) Versioning() version.Number

Versioning returns the client version number.

func (*Client) VsysImport

func (c *Client) VsysImport(loc, tmpl, ts, vsys string, names []string) error

VsysImport imports the given names into the specified template / vsys.

func (*Client) VsysUnimport

func (c *Client) VsysUnimport(loc, tmpl, ts string, names []string) error

VsysUnimport removes the given names from all (template, optional) vsys.

func (*Client) WaitForJob

func (c *Client) WaitForJob(id uint, sleep time.Duration, extras, resp interface{}) error

WaitForJob polls the device, waiting for the specified job to finish.

The sleep param is the length of time to wait between polling for job completion.

The extras param should be either nil or a url.Values{} to be mixed in with the constructed request.

If you want to unmarshal the response into a struct, then pass in a pointer to the struct for the "resp" param. If you just want to know if the job completed with a status other than "FAIL", you only need to check the returned error message.

In the case that there are multiple errors returned from the job, the first error is returned as the error string, and no unmarshaling is attempted.

func (*Client) WaitForLogs

func (c *Client) WaitForLogs(id uint, sleep, timeout time.Duration, ans interface{}) ([]byte, error)

WaitForLogs performs repeated log retrieval operations until the log job is complete or the timeout is reached.

Specify a timeout of zero to wait indefinitely.

The ans param should be a pointer to a struct to unmarshal the response into or nil.

Any response received from the server is returned, along with any errors encountered.

type Firewall

type Firewall struct {
	Client

	// Namespaces
	Predefined  *predefined.Firewall
	Network     *netw.Firewall
	Device      *dev.Firewall
	Policies    *poli.Firewall
	Objects     *objs.FwObjs
	Licensing   *licen.Licen
	UserId      *userid.UserId
	Vsys        *vsys.Firewall
	PanosPlugin *panosplugin.Firewall
}

Firewall is a firewall specific client, providing version safe functions for the PAN-OS Xpath API methods. After creating the object, invoke Initialize() to prepare it for use.

It has the following namespaces:

• Predefined
• Network
• Device
• Policies
• Objects
• Licensing
• UserId

func (*Firewall) GetDhcpInfo

func (c *Firewall) GetDhcpInfo(i string) (map[string]string, error)

GetDhcpInfo returns the DHCP client information about the given interface.

func (*Firewall) Initialize

func (c *Firewall) Initialize() error

Initialize does some initial setup of the Firewall connection, retrieves the API key if it was not already present, then performs "show system info" to get the PAN-OS version. The full results are saved into the client's SystemInfo map.

If not specified, the following is assumed:

• Protocol: https
• Port: (unspecified)
• Timeout: 10
• Logging: LogAction | LogUid

func (*Firewall) InitializeUsing

func (c *Firewall) InitializeUsing(filename string, chkenv bool) error

InitializeUsing does Initialize(), but takes in a filename that contains fallback authentication credentials if they aren't specified.

The order of preference for auth / connection settings is:

* explicitly set * environment variable (set chkenv to true to enable this) * json file

type McreMsg

type McreMsg struct {
	Line    []util.CdataText `xml:"line"`
	Message string           `xml:",chardata"`
}

type MultiConfigResponseElement

type MultiConfigResponseElement struct {
	XMLName xml.Name `xml:"response"`
	Status  string   `xml:"status,attr"`
	Code    int      `xml:"code,attr"`
	Id      string   `xml:"id,attr,omitempty"`
	Msg     McreMsg  `xml:"msg"`
}

MultiConfigResponseElement is a single response from a multi-config request.

func (*MultiConfigResponseElement) Message

func (m *MultiConfigResponseElement) Message() string

func (*MultiConfigResponseElement) Ok

func (m *MultiConfigResponseElement) Ok() bool

type MultiConfigure

type MultiConfigure struct {
	XMLName xml.Name `xml:"multi-configure-request"`
	Reqs    []MultiConfigureRequest
}

MultiConfigure is a container object for making a type=multi-config call.

func (*MultiConfigure) IncrementalIds

func (m *MultiConfigure) IncrementalIds()

IncrementalIds assigns incremental ID numbers to all requests.

Any request that already has an ID is skipped, and the number is discarded.

type MultiConfigureRequest

type MultiConfigureRequest struct {
	XMLName xml.Name
	Id      string `xml:"id,attr,omitempty"`
	Xpath   string `xml:"xpath,attr"`
	Data    interface{}
}

MultiConfigureRequest is an individual request in a MultiConfigure instance.

These are built up automatically when invoking Client.Set / Client.Edit after Client.PrepareMultiConfigure is invoked.

type MultiConfigureResponse

type MultiConfigureResponse struct {
	XMLName xml.Name                     `xml:"response"`
	Status  string                       `xml:"status,attr"`
	Code    int                          `xml:"code,attr"`
	Results []MultiConfigResponseElement `xml:"response"`
}

MultiConfigureResponse is a struct to handle the response from multi-config commands.

func (*MultiConfigureResponse) Error

func (m *MultiConfigureResponse) Error() string

Error returns the error if there was one.

func (*MultiConfigureResponse) Ok

func (m *MultiConfigureResponse) Ok() bool

Ok returns if there was an error or not.

type Panorama

type Panorama struct {
	Client

	// Namespaces
	Predefined *predefined.Panorama
	Device     *dev.Panorama
	Licensing  *licen.Licen
	UserId     *userid.UserId
	Panorama   *pnrm.Panorama
	Objects    *objs.PanoObjs
	Policies   *poli.Panorama
	Network    *netw.Panorama
	Vsys       *vsys.Panorama
}

Panorama is a panorama specific client, providing version safe functions for the PAN-OS Xpath API methods. After creating the object, invoke Initialize() to prepare it for use.

It has the following namespaces:

• Licensing
• UserId

func (*Panorama) CreateVmAuthKey

func (c *Panorama) CreateVmAuthKey(hours int) (VmAuthKey, error)

CreateVmAuthKey creates a VM auth key to bootstrap a VM-Series firewall.

VM auth keys are only valid for the number of hours specified.

func (*Panorama) GetVmAuthKeys

func (c *Panorama) GetVmAuthKeys() ([]VmAuthKey, error)

GetVmAuthKeys gets the list of VM auth keys.

func (*Panorama) Initialize

func (c *Panorama) Initialize() error

Initialize does some initial setup of the Panorama connection, retrieves the API key if it was not already present, then performs "show system info" to get the PAN-OS version. The full results are saved into the client's SystemInfo map.

If not specified, the following is assumed:

• Protocol: https
• Port: (unspecified)
• Timeout: 10
• Logging: LogAction | LogUid

func (*Panorama) InitializeUsing

func (c *Panorama) InitializeUsing(filename string, chkenv bool) error

InitializeUsing does Initialize(), but takes in a filename that contains fallback authentication credentials if they aren't specified.

The order of preference for auth / connection settings is:

* explicitly set * environment variable (set chkenv to true to enable this) * json file

func (*Panorama) RevokeVmAuthKey

func (c *Panorama) RevokeVmAuthKey(key string) error

RemoveVmAuthKey revokes a VM auth key.

type VmAuthKey

type VmAuthKey struct {
	AuthKey string `xml:"vm-auth-key"`
	Expiry  string `xml:"expiry-time"`
	Expires time.Time
}

VmAuthKey is a VM auth key paired with when it expires.

The Expiry field is the string returned from PAN-OS, while the Expires field is an attempt at parsing the Expiry field.

func (*VmAuthKey) ParseExpires

func (o *VmAuthKey) ParseExpires(clock time.Time)

ParseExpires sets Expires from the Expiry field.

Since PAN-OS does not output timezone information with the expirations, the current PAN-OS time is retrieved, which does contain timezone information. Then in the string parsing for Expires, the location information of the system clock is applied.