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.