urlquery

package module
v0.0.0-...-6f72bef Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2025 License: Apache-2.0 Imports: 9 Imported by: 2

README

urlquery-api-go

Go implementation of the public REST API for http://urlquery.net

https://urlquery.net/doc/api/public/v1

Get a APIKEY by creating a account at: https://urlquery.net/user/signup

Usage example

package main

import (
	"flag"
	"fmt"
	"log"
	"os"
	"time"
	"github.com/urlquery/urlquery-api-go"
)

// Command-line arguments
var key = flag.String("apikey", "", "urlquery API key")
var url = flag.String("submit", "", "submit url")

func main() {
	flag.Parse()

	if *url == "" || *key == "" {
		flag.PrintDefaults()
		fmt.Println("\nPlease provide a APIKEY and URL to submit")
		os.Exit(0)
	}
	urlquery.SetDefaultKey(*key)

	submission := urlquery.SubmitJob{
		Url:    *url,
		Access: "public", // public, restricted, private
	}

	queue, err := urlquery.Submit(submission)
	if err != nil {
		log.Fatal("submission failed:", err)
	}

	// status -> queued, processing, done, failed
	for queue.Status != "done" && queue.Status != "failed" {
		time.Sleep(3 * time.Second)
		queue, err = urlquery.GetQueueStatus(queue.QueueID)
		if err != nil {
			panic(err)
		}

		fmt.Printf("\rStatus: %s", queue.Status)
	}

	if queue.Status == "done" {
		report, _ := urlquery.GetReport(queue.ReportID)
		fmt.Println(report.String())
		fmt.Println("\nReport at: https://urlquery.net/report/" + report.ID)

	}

	if queue.Status == "failed" {
		fmt.Println("Processing URL failed!")
	}

}

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotFound            = errors.New("not found")
	ErrForbidden           = errors.New("forbidden")
	ErrUnauthorized        = errors.New("unauthorized")
	ErrTooManyRequests     = errors.New("too many requests")
	ErrUnprocessableEntity = errors.New("unprocessable entity")
	ErrUnexpectedStatus    = errors.New("unexpected status code")
)
View Source 
var (
	DefaultClient = NewClient("")
)

Functions

func DecodeResponse 

func DecodeResponse(resp *http.Response, target interface{}) error

DecodeResponse decodes the HTTP response body.

func DeleteReport 

func DeleteReport(report_id string) error

func GetDomainGraph 

func GetDomainGraph(report_id string) ([]byte, error)

func GetResource 

func GetResource(report_id string, hash string)

func GetScreenshot 

func GetScreenshot(report_id string) ([]byte, error)

func NewSearchParams 

func NewSearchParams(query string) *searchParams

func SetDefaultKey 

func SetDefaultKey(apikey string)

func SetUserNotifyWebhook 

func SetUserNotifyWebhook(webhook string) error

func SetUserNotifyWebhookEnable 

func SetUserNotifyWebhookEnable(enabled bool) error

Types

type Alerts 

type Alerts struct {
	IDSAlerts      []IDSAlert      `json:"ids"`
	AnalyzerAlerts []AnalyzerAlert `json:"analyzer"`
	UrlqueryAlerts []UrlqueryAlert `json:"urlquery"`
}

type AnalyzerAlert 

type AnalyzerAlert struct {
	SensorName  string `json:"sensor_name"`
	SensorType  string `json:"sensor_type"`
	Description string `json:"description"`

	ScanDate     string             `json:"scan_date"`
	Alert        string             `json:"alert"`
	Trigger      string             `json:"trigger"`
	Verdict      string             `json:"verdict"`
	Severity     string             `json:"severity"`
	Comment      string             `json:"comment"`
	ResourceLink *string            `json:"link"`
	Meta         *map[string]string `json:"meta"`
}

type AnalyzerSensor 

type AnalyzerSensor struct {
	SensorName  string `json:"sensor_name"`
	Type        string `json:"type"`
	Description string `json:"description"`
	Link        string `json:"link"`

	Alerts []AnalyzerAlert `json:"alerts"`
}

type CertInfo 

type CertInfo struct {
	Subject     SubjectInfo     `json:"subject"`
	Issuer      IssuerInfo      `json:"issuer"`
	Validity    ValidityInfo    `json:"validity"`
	Fingerprint FingerprintInfo `json:"fingerprint"`
}

type Client 

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

Client represents the REST API client.

func NewClient 

func NewClient(key string) *Client

func (*Client) DeleteReport 

func (c *Client) DeleteReport(report_id string) error

func (*Client) Do 

func (c *Client) Do(req *http.Request) (*http.Response, error)

MakeRequest makes an HTTP request to the API.

func (*Client) DoRequest 

func (c *Client) DoRequest(method string, path string, body io.Reader) (*http.Response, error)

DoRequest makes an HTTP request to the API.

func (*Client) GetDomainGraph 

func (c *Client) GetDomainGraph(report_id string) ([]byte, error)

func (*Client) GetQueueStatus 

func (c *Client) GetQueueStatus(queue_id string) (*QueuedJob, error)

func (*Client) GetReport 

func (c *Client) GetReport(report_id string) (*Report, error)

func (Client) GetResource 

func (api Client) GetResource(report_id string, hash string) ([]byte, error)

func (*Client) GetScreenshot 

func (c *Client) GetScreenshot(report_id string) ([]byte, error)

func (*Client) GetUser 

func (c *Client) GetUser() (*PublicUserInfo, error)

func (*Client) NewRequest 

func (c *Client) NewRequest(method string, path string, body io.Reader) (*http.Request, error)

func (*Client) ReputationCheck 

func (c *Client) ReputationCheck(query string) (*ReputationResult, error)

func (*Client) Search 

func (c *Client) Search(queryParams *searchParams) (*SearchResponse, error)

func (*Client) SetUserNotifyWebhook 

func (c *Client) SetUserNotifyWebhook(webhook string) error

func (*Client) SetUserNotifyWebhookEnable 

func (c *Client) SetUserNotifyWebhookEnable(enabled bool) error

func (*Client) Submit 

func (c *Client) Submit(submit SubmitJob) (*QueuedJob, error)

func (*Client) WithApiKey 

func (c *Client) WithApiKey(key string) *Client

type FileAnalyzer 

type FileAnalyzer struct {
	SensorName  string `json:"sensor_name"`
	Description string `json:"description"`

	ScanDate string  `json:"scan_date"`
	Trigger  string  `json:"trigger"`
	Verdict  string  `json:"verdict"`
	Comment  string  `json:"comment"`
	Link     *string `json:"link"`
}

type FileObservation 

type FileObservation struct {
	Md5    string `json:"md5"`
	Sha1   string `json:"sha1"`
	Sha256 string `json:"sha256"`
	Sha512 string `json:"sha512"`
	Magic  string `json:"magic"`
	Size   int    `json:"size"`

	Url URL `json:"url"`
	Ip  IP  `json:"ip"`

	Alerts struct {
		AnalyzerAlerts []AnalyzerAlert `json:"analyzer"`
	} `json:"alerts"`
}

type FingerprintInfo 

type FingerprintInfo struct {
	Sha1   string `json:"sha1"`
	Sha256 string `json:"sha256"`
}

type HttpContent 

type HttpContent struct {
	Size     int    `json:"size"`
	MimeType string `json:"mime_type"`
	Magic    string `json:"magic"`
	Md5      string `json:"md5"`
	Sha1     string `json:"sha1"`
	Sha256   string `json:"sha256"`
	Sha512   string `json:"sha512"`
	Data     []byte `json:"data"`
}

type HttpCookie 

type HttpCookie struct {
	Name     string `json:"name"`
	Value    string `json:"value"`
	Path     string `json:"path"`
	Domain   string `json:"domain"`
	Expires  string `json:"expire"`
	HttpOnly bool   `json:"http_only"` // HAR - TRUE if the cookie is HTTP only
	Secure   bool   `json:"secure"`    // HAR - TRUE if the cookie was transmitted of ssl, otherwise false
}

type HttpHeaderValue 

type HttpHeaderValue struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type HttpPostData 

type HttpPostData struct {
	MimeType string `json:"mime_type"`

	// Note that text and params fields are mutually exclusive.
	Params []HttpPostDataParams `json:"params"`
	Text   string               `json:"text"`
}

type HttpPostDataParams 

type HttpPostDataParams struct {
	Name        string `json:"name"`
	Value       string `json:"value"`
	Filename    string `json:"filename"`
	ContentType string `json:"content_type"`
}

type HttpRequest 

type HttpRequest struct {
	Raw     string            `json:"raw"`
	Headers []HttpHeaderValue `json:"headers"`
	Cookies []HttpHeaderValue `json:"cookies"`

	Method string `json:"method"`
}

type HttpResponse 

type HttpResponse struct {
	Raw     string            `json:"raw"`
	Headers []HttpHeaderValue `json:"headers"`
	Cookies []HttpHeaderValue `json:"cookies"`

	StatusCode string `json:"status_code"`
	StatusText string `json:"status_text"`

	Content HttpContent `json:"data"`
}

type HttpSecurityInfo 

type HttpSecurityInfo struct {
	CipherSuite   string   `json:"cipher_suite"`
	KeyGroupName  string   `json:"key_group_name"`
	SignatureName string   `json:"signature_name"`
	Protocol      string   `json:"protocol"`
	Cert          CertInfo `json:"cert"`
}

type HttpTimings 

type HttpTimings struct {
	Blocked int `json:"blocked"` // Time spent in a queue waiting for a network connection. Use -1 if the timing does not apply to the current request.
	DNS     int `json:"dns"`     // DNS resolution time. The time required to resolve a host name. Use -1 if the timing does not apply to the current request.
	Connect int `json:"connect"` // Time required to create TCP connection. Use -1 if the timing does not apply to the current request.
	Send    int `json:"send"`    // Time required to send HTTP request to the server.
	Wait    int `json:"wait"`    // Waiting for a response from the server.
	Receive int `json:"receive"` // Time required to read entire response from the server (or cache).
	SSL     int `json:"ssl"`     // Time required for SSL/TLS negotiation. If this field is defined then the time is also included in the connect field (to ensure backward compatibility with HAR 1.1). Use -1 if the timing does not apply to the current request.
}

type HttpTransaction 

type HttpTransaction struct {
	Url                 URL    `json:"url"`
	Ip                  IP     `json:"ip"`
	IsNavigationRequest bool   `json:"is_navigation_request"`
	ResourceType        string `json:"resource_type"`
	RequestedBy         string `json:"requested_by"`

	Date      string `json:"date"`      // ISO8601 -  YYYY-MM-DDThh:mm:ss.sTZD
	Timestamp int64  `json:"timestamp"` // unix epoch

	HttpVersion   string            `json:"http_version"`
	SecurityState string            `json:"security_state"` // Can be "secure", "insecure", "broken"
	SecurityInfo  *HttpSecurityInfo `json:"security_info"`

	Request  HttpRequest  `json:"request"`
	Response HttpResponse `json:"response"`

	TotalTimeUsed int         `json:"time_used"` // Total time used by the reques/response in milliseconds
	Timings       HttpTimings `json:"timings"`
	Alerts        Alerts      `json:"alerts"`
}

type IDSAlert 

type IDSAlert struct {
	SensorName string `json:"sensor_name"`
	Date       string `json:"date"`
	Timestamp  int    `json:"timestamp"`
	IpDst      IP     `json:"ip_dst"`
	IpSrc      IP     `json:"ip_src"`
	Severity   string `json:"severity"`
	Alert      string `json:"alert"`
}

type IDSSensor 

type IDSSensor struct {
	SensorName  string `json:"sensor_name"`
	Description string `json:"description"`

	Alerts []IDSAlert `json:"alerts"`
}

type IP 

type IP struct {
	Addr string `json:"addr"`
	Port int    `json:"port"`

	ASN         int    `json:"asn"`
	AS          string `json:"as"`
	Country     string `json:"country"`
	CountryCode string `json:"country_code"`
}

type IssuerInfo 

type IssuerInfo struct {
	CommonName   string `json:"commonName"`
	Organization string `json:"organization"`
}

type JSCode 

type JSCode struct {
	Md5    string `json:"md5"`
	Sha1   string `json:"sha1"`
	Sha256 string `json:"sha256"`
	Sha512 string `json:"sha512"`
	Size   int    `json:"size"`
	Data   string `json:"data"`

	FirstSeen string `json:"first_seen"`
	LastSeen  string `json:"last_seen"`
	TimesSeen int    `json:"times_seen"`

	Alerts Alerts `json:"alerts"`
}

type JSSourceCode 

type JSSourceCode struct {
	Url URL `json:"url"`
	Ip  IP  `json:"ip"`

	IntroductionType string `json:"introduction_type"`
	IsInline         bool   `json:"is_inline"`
	JSCode
}

type JavaScriptCode 

type JavaScriptCode struct {
	Script []JSSourceCode `json:"script"`
	Eval   []JSCode       `json:"eval"`
	Write  []JSCode       `json:"write"`
}

type Notify 

type Notify struct {
	Webhook struct {
		Enabled bool   `json:"enabled"`
		URL     string `json:"url"`
	} `json:"webhook"`
}

type PublicUserInfo 

type PublicUserInfo struct {
	ID       string `json:"id"`
	Created  string `json:"created"`
	Username string `json:"username"`
	Email    string `json:"email"`
	Role     string `json:"role"`
	Group    string `json:"group"`
	Notify   Notify `json:"notify"`
	ApiKey   string `json:"apikey"`
}

User

func GetUser 

func GetUser() (*PublicUserInfo, error)

type QueuedJob 

type QueuedJob struct {
	QueueID  string `json:"queue_id"`
	ReportID string `json:"report_id"`
	Status   string `json:"status"`

	Url URL `json:"url"`
	Ip  IP  `json:"ip"`

	UserAgent string `json:"useragent"`
	Referer   string `json:"referer"`
	ExitNode  string `json:"exit_node"`
	Owner     string `json:"owner"`
	Access    string `json:"access"`
	RunTime   int    `json:"run_time"`
}

func GetQueueStatus 

func GetQueueStatus(queue_id string) (*QueuedJob, error)

func Submit 

func Submit(submit SubmitJob) (*QueuedJob, error)

func (QueuedJob) Bytes 

func (j QueuedJob) Bytes() []byte

func (QueuedJob) String 

func (j QueuedJob) String() string

type Report 

type Report struct {
	ReportOverview

	FileDetections []FileObservation `json:"files"`

	Sensors struct {
		NetworkSensors  []IDSSensor      `json:"ids"`
		AnalyzerSensors []AnalyzerSensor `json:"analyzer"`
		UrlQueryAlerts  []UrlqueryAlert  `json:"urlquery"`
	} `json:"sensors"`

	Javascript       JavaScriptCode    `json:"javascript"`
	HttpTransactions []HttpTransaction `json:"http"`
}

RFC3339 - is the default time format with RFC3339Nano used sometimes (http transactions)

func GetReport 

func GetReport(report_id string) (*Report, error)

func (*Report) Bytes 

func (r *Report) Bytes() []byte

func (*Report) String 

func (r *Report) String() string

type ReportOverview 

type ReportOverview struct {
	ID      string   `json:"report_id"`
	Version int      `json:"version"`
	Status  string   `json:"status"`
	Tags    []string `json:"tags"`
	Date    string   `json:"date"` // RFC3339 -  "2006-01-02T15:04:05Z07:00"

	Url URL `json:"url"`
	Ip  IP  `json:"ip"`

	Final struct {
		Url   URL    `json:"url"`
		Title string `json:"title"`
	} `json:"final"`

	Submit struct {
		Tags []string          `json:"tags"`
		Meta map[string]string `json:"meta"`
	} `json:"submit"`

	// Settings the report was run  with
	ReportSettings struct {
		UserAgent string            `json:"useragent"`
		Referer   string            `json:"referer"`
		Cookies   map[string]string `json:"cookies"` // Cookie[<domain>]<cookie string>
		Access    string            `json:"access"`
		ExitNode  string            `json:"exit_node"`
	} `json:"settings"`

	Stats struct {
		AlertCount struct {
			Ids      int `json:"ids"`
			Urlquery int `json:"urlquery"`
			Analyzer int `json:"analyzer"`
		} `json:"alert_count"`
	} `json:"stats"`

	Summary []ReportSummary `json:"summary"`
}

type ReportSummary 

type ReportSummary struct {
	Fqdn string `json:"fqdn"`

	Ip IP `json:"ip"`

	DomainRegistered string `json:"domain_registered"`
	DomainRank       int    `json:"domain_rank"`
	FirstSeen        string `json:"first_seen"`
	LastSeen         string `json:"last_seen"`

	AlertCount   int `json:"alert_count"`
	RequestCount int `json:"request_count"`
	ReceivedData int `json:"received_data"`
	SentData     int `json:"sent_data"`

	Comment string   `json:"comment"`
	Tags    []string `json:"tags"`
}

type ReputationResult 

type ReputationResult struct {
	Url     string `json:"url"`
	Verdict string `json:"verdict"`
}

func ReputationCheck 

func ReputationCheck(query string) (*ReputationResult, error)

func (ReputationResult) String 

func (r ReputationResult) String() string

type SearchResponse 

type SearchResponse struct {
	Query     string           `json:"query"`
	TotalHits int              `json:"total_hits"`
	TimeUsed  string           `json:"timeused"`
	Limit     int              `json:"limit"`
	Offset    int              `json:"offset"`
	Reports   []ReportOverview `json:"reports"`
}
func Search(queryParams *searchParams) (*SearchResponse, error)

func (*SearchResponse) Bytes 

func (sr *SearchResponse) Bytes() []byte

func (*SearchResponse) String 

func (sr *SearchResponse) String() string

type SubjectInfo 

type SubjectInfo struct {
	CommonName   string `json:"commonName"`
	Organization string `json:"organization"`
}

type SubmitJob 

type SubmitJob struct {
	Url  string            `json:"url"`
	Tags []string          `json:"tags"`
	Meta map[string]string `json:"meta"`

	UserAgent string `json:"useragent"`
	Referer   string `json:"referer"`
	ExitNode  string `json:"exit_node"`
	Access    string `json:"access"` // public, protected, private
}

func (SubmitJob) Bytes 

func (j SubmitJob) Bytes() []byte

func (SubmitJob) String 

func (j SubmitJob) String() string

type URL 

type URL struct {
	Schema string `json:"schema"`
	Addr   string `json:"addr"`
	Fqdn   string `json:"fqdn"`
	Domain string `json:"domain"`
	TLD    string `json:"tld"`
}

type UrlqueryAlert 

type UrlqueryAlert struct {
	SensorName string   `json:"sensor_name"`
	Alert      string   `json:"alert"`
	Verdict    string   `json:"verdict"`
	Severity   string   `json:"severity"`
	Comment    string   `json:"comment"`
	Tags       []string `json:"tags"`
}

type UrlqueryApiError 

type UrlqueryApiError struct {
	StatusCode int
	Message    string
}

UrlqueryApiError represents an error returned by the API.

func (*UrlqueryApiError) Error 

func (e *UrlqueryApiError) Error() string

type ValidityInfo 

type ValidityInfo struct {
	Start string `json:"start"`
	End   string `json:"end"`
}

Source Files

View all Source files

Directories

Path Synopsis
example
submit

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.