abuseipdbgo

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

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

 Go to latest Published: Jun 15, 2023 License: BSD-3-Clause Imports: 13 Imported by: 0

README

abuseipdb-go

An AbuseIPDB API library for Go

Usage

Add the library to your project with go get

go get github.com/existentiality/abuseipdb-go

Import the module

import "github.com/existentiality/abuseipdb-go"

Create the client

client := abuseipdbgo.New("YOUR_API_KEY_HERE")

Functions

Checking an IP
// Check the IP "1.1.1.1" for reports within the last 30 days 
client.Check("1.1.1.1", 30)
Reporting an IP
// Report the IP "127.0.0.1" for an SSH Brute Force attack
client.Report("127.0.0.1", []ReportCategory{CategorySSH, CategoryBruteForce}, "SSH Brute Force: <logs>")
Getting the reports of an IP
// Get reports for the IP "1.1.1.1" on page 1 with 25 results per page
// Within the last 30 days
client.GetReports("1.1.1.1", 1, 25, 30)
Checking the reports of an IP Block
// Check the IP Block "127.0.0.0/24" (127.0.0.0-127.0.0.255) for recent reports within the past 30 days
client.CheckBlock("127.0.0.0/24", 30)
Getting an IP Blacklsit
// Get a blacklist of 10,000 IPs
client.GetBlacklist(10000)
Bulk reporting several IPs
toReport := NewBulkReportBuilder().
		AddReport("127.0.0.1", []ReportCategory{CategoryBlogSpam}, time.Now(), "Blog Spam").
		AddReport("127.0.0.3", []ReportCategory{CategorySSH, CategoryBruteForce}, time.Now(), "SSH Brute Force").
		Build()

client.BulkReport(toReport)
Clearing reports of an IP
// Clear all of your account's reports on the IP "1.1.1.1"
client.ClearAddress("1.1.1.1")

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BlacklistResponse 

type BlacklistResponse struct {
	IPAddress            string    `json:"ipAddress"`
	AbuseConfidenceScore int       `json:"abuseConfidenceScore"`
	LastReportedAt       time.Time `json:"lastReportedAt"`
}

type BulkReportBuilder 

type BulkReportBuilder struct {
	Reports []BulkReportLine
}

func NewBulkReportBuilder 

func NewBulkReportBuilder() *BulkReportBuilder

Create a new BulkReportBuilder for formatting BulkReport input

func (*BulkReportBuilder) AddReport 

func (b *BulkReportBuilder) AddReport(ip string, categories []ReportCategory, date time.Time, comment string) *BulkReportBuilder

Add a new Report to the Bulk Report

func (*BulkReportBuilder) Build 

func (b *BulkReportBuilder) Build() string

Format the Bulk report into CSV Format. Can be passed into the BulkReport function

type BulkReportLine 

type BulkReportLine struct {
	IP         string
	Categories []ReportCategory
	Date       time.Time
	Comment    string
}

type BulkReportResponse 

type BulkReportResponse struct {
	SavedReports   int             `json:"savedReports"`
	InvalidReports []InvalidReport `json:"invalidReports"`
}

type CheckBlockResponse 

type CheckBlockResponse struct {
	NetworkAddress   string            `json:"networkAddress"`
	Netmask          string            `json:"netmask"`
	MinAddress       string            `json:"minAddress"`
	MaxAddress       string            `json:"maxAddress"`
	NumPossibleHosts int               `json:"numPossibleHosts"`
	AddressSpaceDesc string            `json:"addressSpaceDesc"`
	ReportedAddress  []ReportedAddress `json:"reportedAddress"`
}

type CheckResponse 

type CheckResponse struct {
	IPAddress            string            `json:"ipAddress"`
	IsPublic             bool              `json:"isPublic"`
	IPVersion            int               `json:"ipVersion"`
	IsWhitelisted        bool              `json:"isWhitelisted"`
	AbuseConfidenceScore int               `json:"abuseConfidenceScore"`
	CountryCode          string            `json:"countryCode"`
	CountryName          string            `json:"countryName"`
	UsageType            string            `json:"usageType"`
	ISP                  string            `json:"isp"`
	Domain               string            `json:"domain"`
	Hostnames            []string          `json:"hostnames"`
	TotalReports         int               `json:"totalReports"`
	NumDistinctUsers     int               `json:"numDistinctUsers"`
	LastReportedAt       time.Time         `json:"lastReportedAt"`
	Reports              []ReportCheckData `json:"reports"`
}

type ClearAddressResponse 

type ClearAddressResponse struct {
	NumReportsDeleted int `json:"numReportsDeleted"`
}

type Client 

type Client struct {
	ApiKey string
}

func New 

func New(apiKey string) Client

Create a new AbuseIPDB Client

func (Client) BulkReport 

func (c Client) BulkReport(fileContent string) (*BulkReportResponse, error)

Bulk report IP Addresses from a CSV File

It is recommended to use the BulkReportBuilder to easily generate the correct input for this method. Otherise, see AbuseIPDB's bulk report form for information on how to format the file content

func (Client) Check 

func (c Client) Check(ip string, maxAgeInDays int) (*CheckResponse, error)

Get information on a specific IP Address

ip: The IP Address to Check

maxAgeInDays: How far back in time to check reports, (min 1, max 365) (abuseipdb default: 30)

func (Client) CheckBlock 

func (c Client) CheckBlock(cidr string, maxAgeInDays int) (*CheckBlockResponse, error)

Check an IP Subnet

cidr: The network block to check in CIDR notation (Free Subscription can check up to a /24, Basic up to a /20, and Premium up to a /16)

maxAgeInDays: How far back in days to check for reports (min 1, max 365) (abuseipdb default: 30)

func (Client) ClearAddress 

func (c Client) ClearAddress(ip string) (*ClearAddressResponse, error)

Delete all of your reports for an IP Address Note: This only deletes reports your account has made, it cannot delete reports from other accounts

ip: The IP Address to clear reports for

func (Client) GetBlacklist 

func (c Client) GetBlacklist(limit int) (*[]BlacklistResponse, error)

Get a Blacklist of known malicious IPs Note: This endpoint has restricted parameters limited to AbuseIPDB paid subscribers, if you wish to use those, please use the GetBlacklistSubscriber function

limit: The maximum number of IPs to list (max 10,000 for Free Plan) (abuseipdb default: 10,000)

func (Client) GetBlacklistSubscriber 

func (c Client) GetBlacklistSubscriber(limit, confidenceMinimum int, onlyCountries, exceptCountries []string) (*[]BlacklistResponse, error)

GetBlacklist function with extra parameters that are only usable through an AbuseIPDB paid plan

limit: The maximum number of IPs to list (max 10,000 for Free Plan, 100,000 for Basic, and 500,000 for Premium) (abuseipdb default: 10,000)

confidenceMinimum: The minimum abuse confidence score to show in the blacklist (min 25, max 100) (abuseipdb default: 100)

onlyCountries: only retrieve IPs from the specified countries

exceptCountries: retreive IPs from all countries, except those listed

onlyCountries and exceptCountries are mutually exclusive. Country codes should be given as ISO 3166 alpha-2 codes.

func (Client) GetReports 

func (c Client) GetReports(ip string, page, resultsPerPage, maxAgeInDays int) (*GetReportsResponse, error)

Get the reports for a specific IP Address

ip: The IP Address to get reports for

page: The page to check (min 1)

resultsPerPage: The number of results to return per page (min 1, max 100) (abuseipdb default: 25)

maxAgeInDays: How far back in time to check reports (min 1, max 365) (abuseipdb default: 30)

func (Client) Report 

func (c Client) Report(ip string, categories []ReportCategory, comment string) (*ReportResponse, error)

Report an IP Address

ip: The IP Address to report

categories: A list of categories to report the IP for

comment: Information related to the report (server logs, timestamps, etc.)

type GetReportsResponse 

type GetReportsResponse struct {
	Total           int               `json:"total"`
	Page            int               `json:"page"`
	Count           int               `json:"count"`
	PerPage         int               `json:"perPage"`
	LastPage        int               `json:"lastPage"`
	NextPageURL     string            `json:"nextPageUrl"`
	PreviousPageURL string            `json:"previousPageUrl"`
	Results         []ReportCheckData `json:"results"`
}

type InvalidReport 

type InvalidReport struct {
	Error     string `json:"error"`
	Input     string `json:"input"`
	RowNumber int    `json:"rowNumber"`
}

type ReportCategory 

type ReportCategory int

A specific category to report an IP Address for based on malicious behaviour 

const (
	// Altering DNS records resulting in improper redirection.
	CategoryDNSCompromise ReportCategory = iota + 1
	// Falsifying domain server cache (cache poisoning).
	CategoryDNSPosioning
	// Fraudulent orders.
	CategoryFraudOrders
	// Participating in distributed denial-of-service (usually part of botnet).
	CategoryDDoSAttack
	// Participating in an FTP Brute Force attack
	CategoryFTPBruteForce
	// Oversized IP packet.
	CategoryPingOfDeath
	// Phishing websites and/or email.
	CategoryPhishing
	// Participating in VoIP Fraud
	CategoryFraudVoIP
	// Open proxy, open relay, or Tor exit node.
	CategoryOpenProxy
	// Comment/forum spam, HTTP referer spam, or other CMS spam.
	CategoryWebSpam
	// Spam email content, infected attachments, and phishing emails.
	CategoryEmailSpam
	// CMS blog comment spam.
	CategoryBlogSpam
	// Conjunctive category.
	CategoryVPNIP
	// Scanning for open ports and vulnerable services.
	CategoryPortScan
	// Participating in Hacking
	CategoryHacking
	// Attempts at SQL injection.
	CategorySQLInjection
	// Email sender spoofing.
	CategorySpoofing
	// Credential brute-force attacks on webpage logins and services like SSH, FTP, SIP, SMTP, RDP, etc. This category is seperate from DDoS attacks.
	CategoryBruteForce
	// Webpage scraping (for email addresses, content, etc) and crawlers that do not honor robots.txt. Excessive requests and user agent spoofing can also be reported here.
	CategoryBadWebBot
	// Host is likely infected with malware and being used for other attacks or to host malicious content. The host owner may not be aware of the compromise. This category is often used in combination with other attack categories.
	CategoryExploitedHost
	// Attempts to probe for or exploit installed web applications such as a CMS like WordPress/Drupal, e-commerce solutions, forum software, phpMyAdmin and various other software plugins/solutions.
	CategoryWebAppAttack
	// Secure Shell (SSH) abuse. Use this category in combination with more specific categories.
	CategorySSH
	// Abuse was targeted at an "Internet of Things" type device. Include information about what type of device was targeted in the comments.
	CategoryIoTTargeted
)

type ReportCheckData 

type ReportCheckData struct {
	ReportedAt          time.Time `json:"reportedAt"`
	Comment             string    `json:"comment"`
	Categories          []int     `json:"categories"`
	ReporterID          int       `json:"reporterId"`
	ReporterCountryCode string    `json:"reporterCountryCode"`
	ReporterCountryName string    `json:"reporterCountryName"`
}

type ReportResponse 

type ReportResponse struct {
	IPAddress            string `json:"ipAddress"`
	AbuseConfidenceScore int    `json:"abuseConfidenceScore"`
}

type ReportedAddress 

type ReportedAddress struct {
	IPAddress            string    `json:"ipAddress"`
	NumReports           int       `json:"numReports"`
	MostRecentReport     time.Time `json:"mostRecentReport"`
	AbuseConfidenceScore int       `json:"abuseConfidenceScore"`
	CountryCode          string    `json:"countryCode"`
}

Source Files

View all Source files

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.