README

nimbusec

nimbusec API client in Go

Full documentation on https://kb.nimbusec.com/API/API

Documentation

Index

Constants

View Source
const (
	// EmptyFilter is a filter that matches all fields.
	EmptyFilter = ""

	// DefaultAPI is the default endpoint of the nimbusec API.
	DefaultAPI = "https://api.nimbusec.com/"
)
View Source
const (
	// RoleUser is the restricted role for an user
	RoleUser = "user"

	// RoleAdministrator is the unrestricted role for an user
	RoleAdministrator = "administrator"
)

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is returned by GetXYByName functions if the requested entity can not be found.

Functions

This section is empty.

Types

type API

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

API represents a client to the nimbusec API.

func NewAPI

func NewAPI(rawurl, key, secret string) (*API, error)

NewAPI creates a new nimbusec API client.

func (*API) BuildURL

func (a *API) BuildURL(relpath string, args ...interface{}) string

BuildURL builds the fully qualified url to the nimbusec API.

func (*API) CreateDomain

func (a *API) CreateDomain(domain *Domain) (*Domain, error)

CreateDomain issues the API to create the given domain.

func (*API) CreateDomainEvent

func (a *API) CreateDomainEvent(domain int, log *DomainEvent) error

func (*API) CreateNotification

func (a *API) CreateNotification(user int, notification *Notification) (*Notification, error)

CreateNotification creates the notification for the given user.

func (*API) CreateOrGetDomain

func (a *API) CreateOrGetDomain(domain *Domain) (*Domain, error)

CreateOrGetDomain issues the nimbusec API to create the given domain. Instead of failing when attempting to create a duplicate domain, this method will fetch the remote domain instead.

func (*API) CreateOrGetNotification

func (a *API) CreateOrGetNotification(user int, notification *Notification) (*Notification, error)

CreateOrGetNotifcation issues the nimbusec API to create the given notification. Instead of failing when attempting to create a duplicate notification, this method will fetch the remote notification instead.

func (*API) CreateOrGetUser

func (a *API) CreateOrGetUser(user *User) (*User, error)

CreateOrGetUser issues the nimbusec API to create the given user. Instead of failing when attempting to create a duplicate user, this method will fetch the remote user instead.

func (*API) CreateOrUpdateDomain

func (a *API) CreateOrUpdateDomain(domain *Domain) (*Domain, error)

CreateOrUpdateDomain issues the nimbusec API to create the given domain. Instead of failing when attempting to create a duplicate domain, this method will update the remote domain instead.

func (*API) CreateOrUpdateNotification

func (a *API) CreateOrUpdateNotification(user int, notification *Notification) (*Notification, error)

CreateOrUpdateNotification issues the nimbusec API to create the given notification. Instead of failing when attempting to create a duplicate notification, this method will update the remote notification instead.

func (*API) CreateOrUpdateUser

func (a *API) CreateOrUpdateUser(user *User) (*User, error)

CreateOrUpdateUser issues the nimbusec API to create the given user. Instead of failing when attempting to create a duplicate user, this method will update the remote user instead.

func (*API) CreateToken

func (a *API) CreateToken(token *Token) (*Token, error)

CreateToken issues the nimbusec API to create a new agent token.

func (*API) CreateUser

func (a *API) CreateUser(user *User) (*User, error)

CreateUser issues the nimbusec API to create the given user.

func (*API) Delete

func (a *API) Delete(url string, params Params) error

Delete is a helper for all DELETE request with json payload.

func (*API) DeleteDomain

func (a *API) DeleteDomain(d *Domain, clean bool) error

DeleteDomain issues the API to delete a domain. When clean=false, the domain and all assiciated data will only be marked as deleted, whereas with clean=true the data will also be removed from the nimbusec system.

func (*API) DeleteDomainConfig

func (a *API) DeleteDomainConfig(domain int, key string) error

DeleteDomainConfig issues the API to delete the domain configuration with the provided key.

func (*API) DeleteNotification

func (a *API) DeleteNotification(user int, notification *Notification) error

DeleteNotification deletes the given notification.

func (*API) DeleteUser

func (a *API) DeleteUser(user *User) error

DeleteUser issues the nimbusec API to delete an user. The root user or tennant can not be deleted via this method.

func (*API) DeleteUserConfig

func (a *API) DeleteUserConfig(user int, key string) error

DeleteUserConfig issues the API to delete the user configuration with the provided key.

func (*API) DownloadAgent

func (a *API) DownloadAgent(agent Agent) ([]byte, error)

func (*API) FindAgents

func (a *API) FindAgents(filter string) ([]Agent, error)

func (*API) FindBundles

func (a *API) FindBundles(filter string) ([]Bundle, error)

func (*API) FindDomains

func (a *API) FindDomains(filter string) ([]Domain, error)

FindDomains searches for domains that match the given filter criteria.

func (*API) FindInfected

func (a *API) FindInfected(filter string) ([]Domain, error)

FindInfected searches for domains that have pending Results that match the given filter criteria.

func (*API) FindNotifications

func (a *API) FindNotifications(user int, filter string) ([]Notification, error)

FindNotifications fetches all notifications for the given user that match the filter criteria.

func (*API) FindResults

func (a *API) FindResults(domain int, filter string) ([]Result, error)

FindResults searches for results that match the given filter criteria.

func (*API) FindTokens

func (a *API) FindTokens(filter string) ([]Token, error)

FindTOkens searches for tokens that match the given filter criteria.

func (*API) FindUsers

func (a *API) FindUsers(filter string) ([]User, error)

FindUsers searches for users that match the given filter criteria.

func (*API) Get

func (a *API) Get(url string, params Params, dst interface{}) error

Get is a helper for all GET request with json payload.

func (*API) GetBundle

func (a *API) GetBundle(bundle string) (*Bundle, error)

func (*API) GetDomain

func (a *API) GetDomain(domain int) (*Domain, error)

GetDomain retrieves a domain from the API by its ID.

func (*API) GetDomainApplications

func (a *API) GetDomainApplications(domain int) ([]DomainApplication, error)

func (*API) GetDomainByName

func (a *API) GetDomainByName(name string) (*Domain, error)

GetDomainByName fetches an domain by its name.

func (*API) GetDomainConfig

func (a *API) GetDomainConfig(domain int, key string) (string, error)

GetDomainConfig fetches the requested domain configuration.

func (*API) GetDomainEvent

func (a *API) GetDomainEvent(domain int, filter string, limit int) ([]DomainEvent, error)

func (*API) GetDomainMetadata

func (a *API) GetDomainMetadata(domain int) (*DomainMetadata, error)

func (*API) GetDomainScreenshot

func (a *API) GetDomainScreenshot(domain int) (*Screenshot, error)

func (*API) GetDomainSet

func (a *API) GetDomainSet(user *User) ([]int, error)

GetDomainSet fetches the set of allowed domains for an restricted user.

func (*API) GetImage

func (a *API) GetImage(url string) ([]byte, error)

func (*API) GetIssues

func (a *API) GetIssues() ([]DomainIssues, error)

func (*API) GetNotification

func (a *API) GetNotification(user int, id int) (*Notification, error)

GetNotification fetches a notification by its ID.

func (*API) GetResult

func (a *API) GetResult(domain, result int) (*Result, error)

GetResult fetches a result by its ID.

func (*API) GetSpecificDomainScreenshot

func (a *API) GetSpecificDomainScreenshot(domain int, region, viewport string) (*Screenshot, error)

func (*API) GetToken

func (a *API) GetToken(token int) (*Token, error)

GetToken fetches a token by its ID.

func (*API) GetUser

func (a *API) GetUser(user int) (*User, error)

GetUser fetches an user by its ID.

func (*API) GetUserByLogin

func (a *API) GetUserByLogin(login string) (*User, error)

GetUserByLogin fetches an user by its login name.

func (*API) GetUserConfig

func (a *API) GetUserConfig(user int, key string) (string, error)

GetUserConfig fetches the requested user configuration.

func (*API) LinkDomain

func (a *API) LinkDomain(user *User, domain int) error

LinkDomain links the given domain id to the given user and adds the priviledges for the user to view the domain.

func (*API) ListDomainConfigs

func (a *API) ListDomainConfigs(domain int) ([]string, error)

ListDomainConfigs fetches the list of all available configuration keys for the given domain.

func (*API) ListUserConfigs

func (a *API) ListUserConfigs(user int) ([]string, error)

ListuserConfigs fetches the list of all available configuration keys for the given domain.

func (*API) Post

func (a *API) Post(url string, params Params, src interface{}, dst interface{}) error

Post is a helper for all POST request with json payload.

func (*API) Put

func (a *API) Put(url string, params Params, src interface{}, dst interface{}) error

Put is a helper for all PUT request with json payload.

func (*API) SetDomainConfig

func (a *API) SetDomainConfig(domain int, key string, value string) (string, error)

SetDomainConfig sets the domain configuration `key` to the requested value. This method will create the domain configuration if it does not exist yet.

func (*API) SetUserConfig

func (a *API) SetUserConfig(user int, key string, value string) (string, error)

SetUserConfig sets the user configuration `key` to the requested value. This method will create the user configuration if it does not exist yet.

func (*API) UnlinkDomain

func (a *API) UnlinkDomain(user *User, domain int) error

UnlinkDomain unlinks the given domain id to the given user and removes the priviledges from the user to view the domain.

func (*API) UpdateDomain

func (a *API) UpdateDomain(domain *Domain) (*Domain, error)

UpdateDOmain issues the nimbusec API to update a domain.

func (*API) UpdateDomainSet

func (a *API) UpdateDomainSet(user *User, domains []int) ([]int, error)

UpdateDomainSet updates the set of allowed domains of an restricted user.

func (*API) UpdateNotification

func (a *API) UpdateNotification(user int, notification *Notification) (*Notification, error)

UpdateNotification updates the notification for the given user.

func (*API) UpdateResult

func (a *API) UpdateResult(domain int, result *Result) (*Result, error)

UpdateResult issues the nimbusec API to update a result, all fields except status will be ignored.

func (*API) UpdateUser

func (a *API) UpdateUser(user *User) (*User, error)

UpdateUser issues the nimbusec API to update an user.

type Agent

type Agent struct {
	OS      string `json:"os"`
	Arch    string `json:"arch"`
	Version int    `json:"version"`
	Md5     string `json:"md5"`
	Sha1    string `json:"sha1"`
	Format  string `json:"format"`
	URL     string `json:"url"`
}

type Bundle

type Bundle struct {
	Id         string    `json:"id,omitempty"`
	Name       string    `json:"name"`
	Start      Timestamp `json:"startDate"`
	End        Timestamp `json:"endDate"`
	Quota      string    `json:"quota"`
	Depth      int       `json:"depth"`
	Fast       int       `json:"fast"`
	Deep       int       `json:"deep"`
	Contingent int       `json:"contingent"`
	Active     int       `json:"active"`
	Engines    []string  `json:"engines"`
	Amount     int       `json:"amount"`
	Currency   string    `json:"currency"`
}

type Domain

type Domain struct {
	Id        int      `json:"id,omitempty"` // Unique identification of domain
	Bundle    string   `json:"bundle"`       // ID of assigned bundle
	Name      string   `json:"name"`         // Name of domain (usually DNS name)
	Scheme    string   `json:"scheme"`       // Flag whether the domain uses http or https
	DeepScan  string   `json:"deepScan"`     // Starting point for the domain deep scan
	FastScans []string `json:"fastScans"`    // Landing pages of the domain scanned
}

Domain represents a nimbusec monitored domain.

type DomainApplication

type DomainApplication struct {
	Name       string `json:"name"`
	Version    string `json:"version"`
	Path       string `json:"path"`
	Category   string `json:"category"`
	Source     string `json:"source"`
	Latest     bool   `json:"latest"`
	Vulnerable bool   `json:"vulnerable"`
}

type DomainEvent

type DomainEvent struct {
	Time    Timestamp `json:"time"`
	Event   string    `json:"event"`
	Human   string    `json:"human"`
	Machine string    `json:"machine"`
}

type DomainIssues

type DomainIssues struct {
	DomainID int    `json:"domainId,omitempty"`
	Category string `json:"category"`
	Issues   int    `json:"issues"`
	Severity int    `json:"severity"`
	Src      string `json:"src"`
}

type DomainMetadata

type DomainMetadata struct {
	LastDeepScan Timestamp `json:"lastDeepScan"` // timestamp (in ms) of last external scan of the whole site
	NextDeepScan Timestamp `json:"nextDeepScan"` // timestamp (in ms) for next external scan of the whole site
	LastFastScan Timestamp `json:"lastFastScan"` // timestamp (in ms) of last external scan of the landing pages
	NextFastScan Timestamp `json:"nextFastScan"` // timestamp (in ms) for next external scan of the landing pages
	Agent        Timestamp `json:"agent"`        // status of server agent for the given domain
	Files        int       `json:"files"`        // number of downloaded files/URLs for last deep scan
	Size         int       `json:"size"`         // size of downloaded files for last deep scan (in byte)}
}

type Notification

type Notification struct {
	Id         int    `json:"id,omitempty"` // unique identification of notification
	Domain     int    `json:"domain"`       // domain for which notifications should be sent
	Transport  string `json:"transport"`    // transport over which notifications are sent (mail, sms)
	ServerSide int    `json:"serverside"`   // minimum severity of serverside results before a notification is sent
	Content    int    `json:"content"`      // minimum severity of content results before a notification is sent
	Blacklist  int    `json:"blacklist"`    // minimum severity of backlist results before a notification is sent
}

Notification represents an notification entry for a user and domain.

type Params

type Params map[string]string

Params is an convenience alias for URL query values as used with OAuth.

type Result

type Result struct {
	Id           int     `json:"id,omitempty"` // unique identification of a result
	Status       int     `json:"status"`       // status of the result (1 = pending, 2 = acknowledged, 3 = falsepositive, 4 = removed)
	Event        string  `json:"event"`        // event type of result (e.g added file)
	Category     string  `json:"category"`     // category of result
	Severity     int     `json:"severity"`     // severity level of result (1 = medium to 3 = severe)
	Probability  float64 `json:"probability"`  // probability the result is critical
	SafeToDelete bool    `json:"safeToDelete"` // flag indicating if the file can be safely deleted without loosing user data
	CreateDate   int     `json:"createDate"`   // timestamp (in ms) of the first occurrence
	LastDate     int     `json:"lastDate"`     // timestamp (in ms) of the last occurrence

	Threatname string `json:"threatname"` // name identifying the threat of a result
	Resource   string `json:"resource"`   // affected resource (e.g. file path or URL)
	MD5        string `json:"md5"`        // MD5 hash sum of the affected file
	Filesize   int    `json:"filesize"`   // filesize of the affected file
	Owner      string `json:"owner"`      // file owner of the affected file
	Group      string `json:"group"`      // file group of the affected file
	Permission int    `json:"permission"` // permission of the affected file as decimal integer
	Diff       string `json:"diff"`       // diff of a content change between two scans
	Reason     string `json:"reason"`     // reason why a domain/URL is blacklisted
}

Result represents a finding of the nimbusec service that requires user action.

type Screenshot

type Screenshot struct {
	Target   string `json:"target"`
	Previous struct {
		Date     Timestamp `json:"date"`
		MimeType string    `json:"mime"`
		URL      string    `json:"url"`
	} `json:"previous"`
	Current struct {
		Date     Timestamp `json:"date"`
		MimeType string    `json:"mime"`
		URL      string    `json:"url"`
	} `json:"current"`
}

type Timestamp

type Timestamp struct {
	time.Time
}

func (Timestamp) MarshalJSON

func (t Timestamp) MarshalJSON() ([]byte, error)

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(b []byte) error

type Token

type Token struct {
	Id       int    `json:"id"`       // unique identification of a token
	Name     string `json:"name"`     // given name for a token
	Key      string `json:"key"`      // oauth key
	Secret   string `json:"secret"`   // oauth secret
	LastCall int    `json:"lastCall"` // last timestamp (in ms) an agent used the token
	Version  int    `json:"version"`  // last agent version that was seen for this key
}

Token represents the credentials of an API or agent for the nimbusec API.

type User

type User struct {
	Id           int    `json:"id,omitempty"`           // unique identification of user
	Login        string `json:"login"`                  // login name of user
	Mail         string `json:"mail"`                   // e-mail contact where mail notifications are sent to
	Role         string `json:"role"`                   // role of an user (`administrator` or `user`
	Company      string `json:"company"`                // company name of user
	Surname      string `json:"surname"`                // surname of user
	Forename     string `json:"forename"`               // forename of user
	Title        string `json:"title"`                  // academic title of user
	Mobile       string `json:"mobile"`                 // phone contact where sms notifications are sent to
	Password     string `json:"password,omitempty"`     // password of user (only used when creating or updating a user)
	SignatureKey string `json:"signatureKey,omitempty"` // secret for SSO (only used when creating or updating a user)
}

User represents an human user able to login and receive notifications.