planisphere

package
v0.7.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 13, 2023 License: MIT Imports: 15 Imported by: 1

Documentation

Overview

Package planisphere implents a client for interacting with the Planisphere API

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetVulnerabilityCriticalityWithName added in v0.6.2

func GetVulnerabilityCriticalityWithName(name string) (*int, error)

GetVulnerabilityCriticalityWithName returns the criticality value from the name

func ValidateSelfReportKey

func ValidateSelfReportKey(key string) error

ValidateSelfReportKey makes sure the key we are passing is an actual key

func VulnerabilityCriticalities added in v0.7.0

func VulnerabilityCriticalities() []string

VulnerabilityCriticalities Return a list of criticality names.

Types

type Client

type Client struct {

	// Token for requests
	Username string
	Token    string

	// Base URL for API requests.
	BaseURL *url.URL

	// User agent for client
	UserAgent string

	Department   DepartmentService
	SupportGroup SupportGroupService
	Device       DeviceService
	Subnet       SubnetService
	Report       ReportService
	// contains filtered or unexported fields
}

Client is the beefy part of this SDK. It provides the methods used to interact with the API

func NewClient

func NewClient(username string, token string, httpClient *http.Client) *Client

NewClient generates a new Client object with the given username and password

type DataSource

type DataSource struct {
	Data struct {
		DeviceType   string   `json:"device_type,omitempty" yaml:"device_type,omitempty"`
		MacAddresses []string `json:"mac_addresses,omitempty" yaml:"mac_addresses,omitempty"`
		Manufacturer string   `json:"manufacturer,omitempty" yaml:"manufacturer,omitempty"`
	} `json:"data,omitempty" yaml:"data,omitempty"`
	DataSourceID       float64        `json:"data_source_id,omitempty" yaml:"data_source_id,omitempty"`
	DataSourceName     string         `json:"data_source_name,omitempty" yaml:"data_source_name,omitempty"`
	DataSourcePriority float64        `json:"data_source_priority,omitempty" yaml:"data_source_priority,omitempty"`
	DataTimestamp      string         `json:"data_timestamp,omitempty" yaml:"data_timestamp,omitempty"`
	ExtraData          map[string]any `json:"extra_data,omitempty" yaml:"extra_data,omitempty" csv:"-"`
	Key                string         `json:"key,omitempty" yaml:"key,omitempty"`
	LastActive         string         `json:"last_active,omitempty" yaml:"last_active,omitempty"`
	LastUpdated        string         `json:"last_updated,omitempty" yaml:"last_updated,omitempty"`
	Legacy             bool           `json:"legacy" yaml:"legacy"`
	Quarantined        bool           `json:"quarantined" yaml:"quarantined"`
	ReferencedObjectID float64        `json:"referenced_object_id,omitempty" yaml:"reference_object_id,omitempty"`
	SupportGroupLabel  interface{}    `json:"support_group_label,omitempty" yaml:"support_group_label,omitempty" csv:"-"`
	Type               string         `json:"type,omitempty" yaml:"type,omitempty"`
	URL                string         `json:"url,omitempty" yaml:"url,omitempty"`
}

DataSource represents a source of data for devices to feed from inside of Planisphere

type Department

type Department struct {
	Key  string `json:"key,omitempty"`
	Name string `json:"name,omitempty"`
}

Department represents a department with a key and a name

type DepartmentList

type DepartmentList []Department

DepartmentList is a...list of Departments

type DepartmentService

type DepartmentService interface {
	List(context.Context) (*DepartmentList, *Response, error)
}

DepartmentService is an interface to the Department methods

type DepartmentServiceOp

type DepartmentServiceOp struct {
	// contains filtered or unexported fields
}

DepartmentServiceOp is the operator for the DepartmentService

func (*DepartmentServiceOp) List

List returns a list of all departments

type Device

type Device struct {
	LastActive   *time.Time     `json:"last_active,omitempty" yaml:"last_active,omitempty"`
	Names        DeviceNames    `json:"names,omitempty" yaml:"names,omitempty"`
	CustomFields map[string]any `json:"custom_fields,omitempty" yaml:"custom_fields,omitempty" csv:"-"`
	DataSources  []DataSource   `json:"data_sources,omitempty" yaml:"data_sources,omitempty" csv:"-"`
	// Department         interface{}    `json:"department,omitempty" yaml:"department,omitempty" csv:"department,omitempty"`
	DepartmentKey      string     `json:"department_key,omitempty" yaml:"department_key,omitempty" csv:"department_key,omitempty"`
	DeviceType         string     `json:"device_type,omitempty" yaml:"device_type,omitempty"`
	EndpointMgmtStatus string     `json:"endpoint_mgmt_status,omitempty" yaml:"endpoint_mgmt_status,omitempty" csv:"-"`
	ID                 float64    `json:"id,omitempty" yaml:"id,omitempty"`
	InEndpointMgmt     bool       `json:"in_endpoint_mgmt,omitempty" csv:"-"`
	LastInEndpointMgmt *time.Time `json:"last_in_endpoint_mgmt,omitempty" yaml:"last_in_endpoint_mgmt,omitempty" csv:",omitempty"`
	Legacy             bool       `json:"legacy,omitempty" yaml:"legacy,omitempty" csv:",omitempty"`
	MacAddresses       []struct {
		Address    string     `json:"address,omitempty" yaml:"address,omitempty"`
		LastActive *time.Time `json:"last_active,omitempty" yaml:"last_active,omitempty"`
	} `json:"mac_addresses,omitempty" yaml:"mac_addresses,omitempty" csv:"-"`
	Manufacturer         string            `json:"manufacturer,omitempty" yaml:"manufacturer,omitempty"`
	MemoryMb             float64           `json:"memory_mb,omitempty" yaml:"memory_mb,omitempty"`
	Model                string            `json:"model,omitempty" yaml:"model,omitempty"`
	Notes                string            `json:"notes,omitempty" yaml:"notes,omitempty" csv:"-"`
	Oses                 []Os              `json:"oses,omitempty" yaml:"oses,omitempty" csv:"-"`
	Owner                string            `json:"owner,omitempty" yaml:"owner,omitempty"`
	PurchaseDate         string            `json:"purchase_date,omitempty" yaml:"purchase_date,omitempty"`
	QuarantineReasons    QuarantineReasons `json:"quarantine_reasons,omitempty" yaml:"quarantine_reasons,omitempty" csv:"-"`
	QuarantineRisks      QuarantineRisks   `json:"quarantine_risks,omitempty" yaml:"quarantine_risks,omitempty"`
	Quarantined          bool              `json:"quarantined" yaml:"quarantined"`
	RequiresEndpointMgmt bool              `json:"requires_endpoint_mgmt" yaml:"requires_endpoint_mgmt"`
	Serial               string            `json:"serial,omitempty" yaml:"serial,omitempty"`
	SecurityScore        float64           `json:"security_score" yaml:"security_score" csv:"security_score"`
	SSIDs                SSIDs             `json:"ssids,omitempty" yaml:"ssids,omitempty" csv:"-"`
	Status               string            `json:"status,omitempty" yaml:"status,omitempty"`
	Subnets              []struct {
		GuestNetwork bool       `json:"guest_network,omitempty" yaml:"guest_network"`
		LastActive   *time.Time `json:"last_active,omitempty" yaml:"last_active,omitempty"`
		Name         string     `json:"name,omitempty" yaml:"name,omitempty"`
		Subnet       string     `json:"subnet,omitempty" yaml:"subnet,omitempty"`
	} `json:"subnets,omitempty" yaml:"subnets,omitempty" csv:"-"`
	SupportGroup   SupportGroup `json:"support_group,omitempty" yaml:"support_group,omitempty" csv:"-"`
	SupportGroupID float64      `json:"support_group_id,omitempty" yaml:"support_group_id,omitempty"`
	SupportStaff   []string     `json:"support_staff,omitempty" yaml:"support_staff,omitempty" csv:"-"`
	URL            string       `json:"url,omitempty" yaml:"url,omitempty"`
	UsageType      string       `json:"usage_type,omitempty" yaml:"user_type,omitempty" csv:"-"`
	User           User         `json:"user,omitempty" yaml:"user,omitempty" csv:"-"`
	UserID         int          `json:"user_id,omitempty" yaml:"user_id,omitempty" csv:"-"`
	Vrfs           []struct {
		LastActive *time.Time `json:"last_active,omitempty" yaml:"last_active,omitempty"`
		Vrf        string     `json:"vrf,omitempty" yaml:"vrf,omitempty"`
	} `json:"vrfs,omitempty" yaml:"vrfs,omitempty" csv:"-"`
	Vulnerabilities        *VulnerabilityList `json:"vulnerabilities,omitempty" yaml:"vulnerabilities,omitempty" csv:"-"`
	WarrantyExpirationDate string             `json:"warranty_expiration_date,omitempty" yaml:"warranty_expiration_date,omitempty"`
}

Device represents all that Planisphere knows about a given device

type DeviceList

type DeviceList []Device

DeviceList is a type for multiple Devices

type DeviceName added in v0.7.5

type DeviceName struct {
	Name       string     `json:"name,omitempty" yaml:"name,omitempty"`
	LastActive *time.Time `json:"last_active,omitempty" yaml:"last_active,omitempty"`
}

DeviceName represents a Unique name for a given devices

type DeviceNames added in v0.7.5

type DeviceNames []DeviceName

DeviceNames is a list of DeviceName items

func (DeviceNames) MarshalCSV added in v0.7.5

func (n DeviceNames) MarshalCSV() ([]byte, error)

MarshalCSV tells the csvutil how to marshal this

type DeviceParams

type DeviceParams struct {
	ActiveSince           string `url:"active_since,omitempty"`
	DepartmentDetails     bool   `url:"department_details,omitempty"`
	MacAddress            string `url:"mac_address,omitempty"`
	ShowAll               bool   `url:"show_all,omitempty"`
	ShowCustomFields      bool   `url:"show_custom_fields,omitempty"`
	ShowDataSourceRecords bool   `url:"show_data_source_records,omitempty"`
	ShowEndpointMgmtInfo  bool   `url:"show_endpoint_mgmt_info,omitempty"`
	ShowMacAddress        bool   `url:"show_mac_addresses,omitempty"`
	ShowNames             bool   `url:"show_names,omitempty"`
	ShowNulls             bool   `url:"show_nulls,omitempty"`
	ShowOses              bool   `url:"show_oses,omitempty"`
	ShowQuarantineReasons bool   `url:"show_quarantine_reason,omitempty"`
	ShowSSIDs             bool   `url:"show_ssids,omitempty"`
	ShowSubnets           bool   `url:"show_subnets,omitempty"`
	ShowSupportStaff      bool   `url:"show_support_staff,omitempty"`
	ShowVRFs              bool   `url:"show_vrfs,omitempty"`
	ShowVulnerabilities   bool   `url:"-"`
	SupportGroupDetails   bool   `url:"support_group_details,omitempty"`
	SupportGroupKey       string `url:"support_group_key,omitempty"`
	SupportGroupID        int    `url:"support_group_id,omitempty"`
	UserDetails           bool   `url:"user_details,omitempty"`
}

DeviceParams contains options for Device listings. Full information on these can be found at https://planisphere.oit.duke.edu/api_info

type DeviceService

type DeviceService interface {
	Get(context.Context, int, *DeviceParams) (*Device, *Response, error)
	Vulnerabilities(context.Context, int) (*VulnerabilityList, *Response, error)
	List(context.Context, *DeviceParams) (*DeviceList, *Response, error)
}

DeviceService is an interface to the Device methods

type DeviceServiceOp

type DeviceServiceOp struct {
	// contains filtered or unexported fields
}

DeviceServiceOp is the operator for the Service

func (*DeviceServiceOp) Get

func (svc *DeviceServiceOp) Get(ctx context.Context, id int, params *DeviceParams) (*Device, *Response, error)

Get returns information on a single device

func (*DeviceServiceOp) List

func (svc *DeviceServiceOp) List(ctx context.Context, params *DeviceParams) (*DeviceList, *Response, error)

List returns multiple devices based on the given parameters

func (*DeviceServiceOp) Vulnerabilities

func (svc *DeviceServiceOp) Vulnerabilities(ctx context.Context, id int) (*VulnerabilityList, *Response, error)

Vulnerabilities gets a listing of found vulnerabilities on a given device

type ExternalOSIdentifiers

type ExternalOSIdentifiers map[string]string

ExternalOSIdentifiers is a simple map[string]string for shortcuts to OS IDs

func (*ExternalOSIdentifiers) UnmarshalJSON

func (c *ExternalOSIdentifiers) UnmarshalJSON(data []byte) error

UnmarshalJSON is the custom unmarshaller

type Os

type Os struct {
	DiskEncrypted   bool       `json:"disk_encrypted,omitempty" yaml:"disk_encrypted,omitempty"`
	Hostname        string     `json:"hostname,omitempty" yaml:"hostname,omitempty"`
	LastActive      *time.Time `json:"last_active,omitempty" yaml:"last_active,omitempty"`
	OsFamily        string     `json:"os_family,omitempty" yaml:"os_family,omitempty"`
	OsFullname      string     `json:"os_fullname,omitempty" yaml:"os_fullname,omitempty"`
	OsName          string     `json:"os_name,omitempty" yaml:"os_name,omitempty"`
	UnsupportedDate string     `json:"unsupported_date,omitempty" yaml:"unsupported_date,omitempty"`
}

Os is an Operating System

type QuarantineReason added in v0.7.5

type QuarantineReason struct {
	ID    float64 `json:"id,omitempty"`
	Notes string  `json:"notes,omitempty"`
	Type  string  `json:"type,omitempty"`
}

QuarantineReason represents a reason why a host is under Quarantine

type QuarantineReasons added in v0.7.5

type QuarantineReasons []QuarantineReason

QuarantineReasons is multiple QuarantineReason items

type QuarantineRisk added in v0.7.5

type QuarantineRisk struct {
	Description          string `json:"description,omitempty"`
	NotifyOnly           bool   `json:"notify_only,omitempty"`
	TargetQuarantineDate string `json:"target_quarantine_date,omitempty"`
	Type                 string `json:"type,omitempty"`
}

QuarantineRisk describes why a device is at risk for Quarantining

type QuarantineRisks added in v0.7.5

type QuarantineRisks []QuarantineRisk

QuarantineRisks is a list of QuarantineRisk items

func (QuarantineRisks) MarshalCSV added in v0.7.5

func (q QuarantineRisks) MarshalCSV() ([]byte, error)

MarshalCSV marshals this when called to a csv

type ReportParams

type ReportParams struct {
	ActiveSince             int       `url:"active_since,omitempty"`
	DepartmentKeys          []string  `url:"department_key[],omitempty"`
	Hostname                string    `url:"hostname,omitempty"`
	Names                   string    `url:"names,omitempty"`
	OsNames                 []string  `url:"os_name[],omitempty"`
	SupportGroupIDs         []float64 `url:"support_group_id[],omitempty"`
	QuarantineRisks         []string  `url:"quarantine_risks[],omitempty"`
	VRFs                    []string  `url:"vrfs[],omitempty"`
	User                    string    `url:"user,omitempty"`
	VulnerabilitySeverities []int     `url:"vulnerability_severity[],omitempty"`
	IncludeVulnerablityData bool      `url:"-"`
}

ReportParams is the possible parameters to be passed along when looking at a report

type ReportService

type ReportService interface {
	List(context.Context, *ReportParams) (*DeviceList, *Response, error)
	Get(context.Context, string) (*DeviceList, *Response, error)
}

ReportService is the interface for methods interacting with the report endpoint

type ReportServiceOp

type ReportServiceOp struct {
	// contains filtered or unexported fields
}

ReportServiceOp is the operator for said service

func (*ReportServiceOp) Get added in v0.7.1

func (svc *ReportServiceOp) Get(ctx context.Context, report string) (*DeviceList, *Response, error)

Get returns a report using the url query parameters to /report

func (*ReportServiceOp) List

func (svc *ReportServiceOp) List(ctx context.Context, params *ReportParams) (*DeviceList, *Response, error)

List returns a DeviceList of items matching the given ReportParams

type Response

type Response struct {
	Response *http.Response
}

Response is just a holder for some response data we may want to examine later on

type SSID added in v0.7.5

type SSID struct {
	SSID       string     `json:"ssid,omitempty" yaml:"ssid,omitempty"`
	LastActive *time.Time `json:"last_active,omitempty" yaml:"last_active,omitempty"`
}

SSID is an...SSID, I dunno

type SSIDs added in v0.7.5

type SSIDs []SSID

SSIDs represents multiple SSID items

type SelfReportPayload

type SelfReportPayload struct {
	LastActive time.Time             `json:"last_active,omitempty"`
	Key        string                `json:"key,omitempty"`
	URL        string                `json:"url,omitempty"`
	Data       SelfReportPayloadData `json:"data,omitempty"`
	ExtraData  map[string]string     `json:"extra_data,omitempty"`
}

SelfReportPayload is the payload data plus some additional meta information

func (SelfReportPayload) Submit

func (p SelfReportPayload) Submit(key string) error

Submit pushes the report to the API endpoint

func (SelfReportPayload) SubmitTest

func (p SelfReportPayload) SubmitTest(key string) (*SelfReportTestPayload, error)

SubmitTest sends the payload to the test endpoint

func (SelfReportPayload) Summarize

func (p SelfReportPayload) Summarize() string

Summarize returns a string summary of the payload. This should be used where you want to print the info, but not necessarily the hundreds of lines of installed software

func (SelfReportPayload) Validate

func (p SelfReportPayload) Validate() error

Validate returns an error if the SelfReportPayload is invalid

type SelfReportPayloadData

type SelfReportPayloadData struct {
	OsFullname            string                `json:"os_fullname,omitempty"`
	OsFamily              string                `json:"os_family,omitempty"`
	Serial                string                `json:"serial,omitempty"`
	DepartmentKey         string                `json:"department_key,omitempty"`
	DeviceType            string                `json:"device_type,omitempty"`
	DiskEncrypted         bool                  `json:"disk_encrypted,omitempty"`
	Hostname              string                `json:"hostname,omitempty"`
	InstalledSoftware     [][]string            `json:"installed_software,omitempty"`
	MacAddresses          []string              `json:"mac_addresses,omitempty"`
	Manufacturer          string                `json:"manufacturer,omitempty"`
	MemoryMB              uint64                `json:"memory_mb,omitempty"`
	Model                 string                `json:"model,omitempty"`
	Status                string                `json:"status,omitempty"`
	SupportGroupID        uint64                `json:"support_group_id,omitempty"`
	SupportGroupName      string                `json:"support_group_name,omitempty"`
	UsageType             string                `json:"usage_type,omitempty"`
	Username              string                `json:"username,omitempty"`
	ExternalOSIdentifiers ExternalOSIdentifiers `json:"external_os_identifiers,omitempty"`
}

SelfReportPayloadData is the actual payload for the SelfReport endpoint

type SelfReportTestPayload

type SelfReportTestPayload struct {
	ProcessedRecord SelfReportPayload `json:"processed_record,omitempty"`
	Status          string            `json:"status,omitempty"`
}

SelfReportTestPayload is what we get back when using the test endpoint

type Subnet

type Subnet struct {
	Canonical                string        `json:"canonical,omitempty"`
	Department               interface{}   `json:"department,omitempty"`
	ExcludedFromEndpointMgmt bool          `json:"excluded_from_endpoint_mgmt,omitempty"`
	GuestNetwork             bool          `json:"guest_network,omitempty"`
	Name                     interface{}   `json:"name,omitempty"`
	SupportGroup             interface{}   `json:"support_group,omitempty"`
	VRFs                     []interface{} `json:"vrfs,omitempty"`
}

Subnet is what Planisphere calls a Subnet

type SubnetList

type SubnetList []Subnet

SubnetList is a list of Subnets

type SubnetService

type SubnetService interface {
	List(context.Context) (*SubnetList, *Response, error)
}

SubnetService is the interface to subnet methods

type SubnetServiceOp

type SubnetServiceOp struct {
	// contains filtered or unexported fields
}

SubnetServiceOp is the operator for the SubnetService

func (*SubnetServiceOp) List

func (svc *SubnetServiceOp) List(ctx context.Context) (*SubnetList, *Response, error)

List lists out all subnets known to Planisphere

type SupportGroup

type SupportGroup struct {
	ID                    float64       `json:"id,omitempty" yaml:"id"`
	Key                   string        `json:"key,omitempty" yaml:"key,omitempty"`
	Name                  string        `json:"name,omitempty" yaml:"name,omitempty"`
	ServiceNowDisplayName interface{}   `json:"service_now_display_name,omitempty" yaml:"service_now_display_name,omitempty"`
	ServiceNowSysID       interface{}   `json:"service_now_sys_id,omitempty" yaml:"service_now_sys_id,omitempty"`
	UserNetids            []interface{} `json:"user_netids,omitempty" yaml:"user_netids,omitempty"`
}

SupportGroup represents information about the group that supports a given device

type SupportGroupList

type SupportGroupList []SupportGroup

SupportGroupList contains multiple SupportGroup items

type SupportGroupService

type SupportGroupService interface {
	List(context.Context) (*SupportGroupList, *Response, error)
	KeysWithUser(context.Context, string) ([]string, *Response, error)
	IDsWithUser(context.Context, string) ([]float64, *Response, error)
}

SupportGroupService is the interface providing methods for the support_group endpoint

type SupportGroupServiceOp

type SupportGroupServiceOp struct {
	// contains filtered or unexported fields
}

SupportGroupServiceOp is the Operator for the SupportGroupService endpoint

func (*SupportGroupServiceOp) IDsWithUser added in v0.6.2

func (svc *SupportGroupServiceOp) IDsWithUser(ctx context.Context, user string) ([]float64, *Response, error)

IDsWithUser returns the support group ids when given a user name

func (*SupportGroupServiceOp) KeysWithUser added in v0.6.2

func (svc *SupportGroupServiceOp) KeysWithUser(ctx context.Context, user string) ([]string, *Response, error)

KeysWithUser retrieves support group keys using a username

func (*SupportGroupServiceOp) List

List lists out all SupportGroups

type User added in v0.7.5

type User struct {
	Affiliation   string `json:"affiliation,omitempty"`
	DepartmentKey string `json:"department_key,omitempty"`
	DisplayName   string `json:"display_name,omitempty"`
	ID            int    `json:"id,omitempty"`
	Netid         string `json:"netid,omitempty"`
}

User is a user my friend

type Vulnerability

type Vulnerability struct {
	Current        bool              `json:"current,omitempty" yaml:"current"`
	Data           VulnerabilityData `json:"data,omitempty" yaml:"data,omitempty"`
	DataSourceID   float64           `json:"data_source_id,omitempty" yaml:"data_source_id,omitempty"`
	DataSourceName string            `json:"data_source_name,omitempty" yaml:"data_source_name,omitempty"`
	DataTimestamp  *time.Time        `json:"data_timestamp,omitempty" yaml:"data_timestamp,omitempty"`
	ExtraData      map[string]any    `json:"extra_data,omitempty" yaml:"extra_data,omitempty" csv:"-"`
	Key            string            `json:"key,omitempty" yaml:"key,omitempty"`
	LastActive     *time.Time        `json:"last_active,omitempty" yaml:"last_active,omitempty"`
	LastUpdated    *time.Time        `json:"last_updated,omitempty" yaml:"last_updated,omitempty"`
	URL            string            `json:"url,omitempty" yaml:"url,omitempty"`
}

Vulnerability is a single instance of a found Vulnerability on a device

type VulnerabilityData added in v0.7.0

type VulnerabilityData struct {
	Description           string  `json:"description,omitempty" yaml:"description,omitempty"`
	ExploitAvailable      bool    `json:"exploit_available,omitempty" yaml:"exploit_available"`
	FirstObserved         float64 `json:"first_observed,omitempty" yaml:"first_observed,omitempty"`
	IP                    string  `json:"ip,omitempty" yaml:"ip,omitempty"`
	Port                  string  `json:"port,omitempty" yaml:"port,omitempty"`
	Protocol              string  `json:"protocol,omitempty" yaml:"protocol,omitempty"`
	Solution              string  `json:"solution,omitempty" yaml:"solution,omitempty"`
	VulnerabilityDetails  string  `json:"vulnerability_details,omitempty" yaml:"vulnerability_details,omitempty"`
	VulnerabilitySeverity string  `json:"vulnerability_severity,omitempty" yaml:"vulnerability_severity,omitempty"`
}

VulnerabilityData is the juicy data from a given Vulnerability

type VulnerabilityList

type VulnerabilityList []Vulnerability

VulnerabilityList is multiple vulnerabilities

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL