gmp

README

Greenbone Management Protocol (GMP) Go Client

A modern (Go) client for the Greenbone Management Protocol (GMP), used to interact with Greenbone/OpenVAS vulnerability management servers.

[!CAUTION] Expect some breaking changes/refactors as the library matures.

Features

• Full GMP protocol coverage (commands for tasks, targets, reports, assets, credentials, etc.)
• Strongly-typed request/response structs matching the protocol XML
• Idiomatic Go API: simple, consistent, and easy to extend
• Supports filtering, pagination, and error handling as per GMP
• Works with both TLS and Unix socket connections

Requirements

• Go 1.23+
• Access to a running Greenbone/OpenVAS server with GMP enabled
• Access to the GMP server (typically via TLS or Unix socket)

---

[!NOTE] An example docker-compose.yml is provided in the ./hack directory. You can use it to spin up a full GMP test environment with TLS enabled for local development and testing.

---

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/brennoo/go-gmp/client"
	"github.com/brennoo/go-gmp/commands"
	"github.com/brennoo/go-gmp/connections"
)

func main() {
	// Create a TLS connection (set insecure to true for self-signed certs)
	conn, err := connections.NewTLSConnection("gmp.example.com:9390", true)
	if err != nil {
		log.Fatalf("failed to connect: %v", err)
	}
	defer conn.Close()

	// Create a client
	cli := client.New(conn)

	// Authenticate
	auth := &commands.Authenticate{
		Credentials: &commands.AuthenticateCredentials{
			Username: "admin",
			Password: "secret",
		},
	}
	authResp, err := cli.Authenticate(auth)
	if err != nil {
		log.Fatalf("auth failed: %v", err)
	}
	if authResp.Status != "200" {
		log.Fatalf("auth failed: %s (%s)", authResp.Status, authResp.StatusText)
	}
	fmt.Printf("Authenticated! Role: %s, Timezone: %s\n", authResp.Role, authResp.Timezone)

	// Basic query: get tasks
	tasksResp, err := cli.GetTasks(&commands.GetTasks{})
	if err != nil {
		log.Fatalf("get tasks failed: %v", err)
	}
	if tasksResp.Status != "200" {
		log.Fatalf("get tasks failed: %s (%s)", tasksResp.Status, tasksResp.StatusText)
	}
	for _, task := range tasksResp.Task {
		fmt.Printf("Task: %s (ID: %s, Status: %s)\n", task.Name, task.ID, task.Status)
	}
}

How It Works

• Connection: You create a gmp.Connection (TLS or Unix socket). This handles the low-level protocol.
• Client: Pass the connection to client.New() to get a gmp.Client.
• Commands: Each GMP command is a Go struct (e.g., GetTasks).
• Responses: Each command returns a strongly-typed response struct (e.g., GetTasksResponse).
• Error Handling: All client methods return a response and an error. Protocol errors are mapped to Go errors.

Filtering

GMP supports powerful filtering for most list/get commands. You can use the Filter field:

// Get only running tasks, sorted by name
tasksResp, err := cli.GetTasks(&commands.GetTasks{
	Filter: "status=running sort=name",
})
if err != nil {
	log.Fatalf("get tasks failed: %v", err)
}
if tasksResp.Status != "200" {
	log.Fatalf("get tasks failed: %s (%s)", tasksResp.Status, tasksResp.StatusText)
}
for _, task := range tasksResp.Task {
	fmt.Println(task.Name, task.Status)
}

Pagination

[!NOTE] By default, the GMP server returns 10 rows per page if you do not specify the rows filter.

For large result sets, use Filter with rows and first:

// Get the first 10 results for a task
resultsResp, err := cli.GetResults(&commands.GetResults{
	TaskID: "<task-id>",
	Filter: "rows=10 first=1",
})
if err != nil {
	log.Fatalf("get results failed: %v", err)
}
if resultsResp.Status != "200" {
	log.Fatalf("get results failed: %s (%s)", resultsResp.Status, resultsResp.StatusText)
}
for _, result := range resultsResp.Results {
	fmt.Println(result.ID, result.Name)
}

Error Handling

All client methods return a response and an error. If the server returns a protocol error, it is mapped to a Go error:

resp, err := cli.DeleteTask(&commands.DeleteTask{TaskID: "bad-id"})
if err != nil {
	log.Printf("delete failed: %v", err)
}
if resp.Status != "200" {
	log.Printf("delete failed: %s (%s)", resp.Status, resp.StatusText)
}

RawXML: Custom/Unsupported Requests

If you need to send a custom or undocumented GMP command, you can use the RawXML method to send raw XML and receive the raw XML response:

raw := `<get_custom_resource foo="bar"/>`
resp, err := cli.RawXML(raw)
if err != nil {
	log.Fatalf("raw xml failed: %v", err)
}
fmt.Println("Raw response:", resp)

This is useful for experimenting with custom or not-yet-supported GMP commands.

Extending the client

• All major GMP commands are available.
• Each command/response struct is documented and matches the protocol XML.
• You can add new commands by following the same pattern.

Examples

A set of example programs is provided in the examples/ directory

See Also

• Greenbone GMP Protocol Documentation
• Examples

Credits

This package was based on github.com/filewalkwithme/go-gmp.

Documentation

Index

• type Client
• type Connection

Types

type Client

type Client interface {
	// Authentication
	Authenticate(cmd *commands.Authenticate) (resp *commands.AuthenticateResponse, err error)
	DescribeAuth(cmd *commands.DescribeAuth) (resp *commands.DescribeAuthResponse, err error)
	ModifyAuth(cmd *commands.ModifyAuth) (resp *commands.ModifyAuthResponse, err error)

	// User Management
	CreateUser(cmd *commands.CreateUser) (resp *commands.CreateUserResponse, err error)
	ModifyUser(cmd *commands.ModifyUser) (resp *commands.ModifyUserResponse, err error)
	GetUsers(cmd *commands.GetUsers) (resp *commands.GetUsersResponse, err error)
	DeleteUser(cmd *commands.DeleteUser) (resp *commands.DeleteUserResponse, err error)
	CreateRole(cmd *commands.CreateRole) (resp *commands.CreateRoleResponse, err error)
	ModifyRole(cmd *commands.ModifyRole) (resp *commands.ModifyRoleResponse, err error)
	GetRoles(cmd *commands.GetRoles) (resp *commands.GetRolesResponse, err error)
	DeleteRole(cmd *commands.DeleteRole) (resp *commands.DeleteRoleResponse, err error)
	CreatePermission(cmd *commands.CreatePermission) (resp *commands.CreatePermissionResponse, err error)
	ModifyPermission(cmd *commands.ModifyPermission) (resp *commands.ModifyPermissionResponse, err error)
	GetPermissions(cmd *commands.GetPermissions) (resp *commands.GetPermissionsResponse, err error)
	DeletePermission(cmd *commands.DeletePermission) (resp *commands.DeletePermissionResponse, err error)
	CreateGroup(cmd *commands.CreateGroup) (resp *commands.CreateGroupResponse, err error)
	ModifyGroup(cmd *commands.ModifyGroup) (resp *commands.ModifyGroupResponse, err error)
	GetGroups(cmd *commands.GetGroups) (resp *commands.GetGroupsResponse, err error)
	DeleteGroup(cmd *commands.DeleteGroup) (resp *commands.DeleteGroupResponse, err error)

	// Asset Management
	CreateAsset(cmd *commands.CreateAsset) (resp *commands.CreateAssetResponse, err error)
	ModifyAsset(cmd *commands.ModifyAsset) (resp *commands.ModifyAssetResponse, err error)
	GetAssets(cmd *commands.GetAssets) (resp *commands.GetAssetsResponse, err error)
	DeleteAsset(cmd *commands.DeleteAsset) (resp *commands.DeleteAssetResponse, err error)

	// Credential Management
	CreateCredential(cmd *commands.CreateCredential) (resp *commands.CreateCredentialResponse, err error)
	ModifyCredential(cmd *commands.ModifyCredential) (resp *commands.ModifyCredentialResponse, err error)
	GetCredentials(cmd *commands.GetCredentials) (resp *commands.GetCredentialsResponse, err error)
	DeleteCredential(cmd *commands.DeleteCredential) (resp *commands.DeleteCredentialResponse, err error)

	// Target Management
	CreateTarget(cmd *commands.CreateTarget) (resp *commands.CreateTargetResponse, err error)
	ModifyTarget(cmd *commands.ModifyTarget) (resp *commands.ModifyTargetResponse, err error)
	GetTargets(cmd *commands.GetTargets) (resp *commands.GetTargetsResponse, err error)
	DeleteTarget(cmd *commands.DeleteTarget) (resp *commands.DeleteTargetResponse, err error)

	// Task Management
	CreateTask(cmd *commands.CreateTask) (resp *commands.CreateTaskResponse, err error)
	ModifyTask(cmd *commands.ModifyTask) (resp *commands.ModifyTaskResponse, err error)
	GetTasks(cmd *commands.GetTasks) (resp *commands.GetTasksResponse, err error)
	DeleteTask(cmd *commands.DeleteTask) (resp *commands.DeleteTaskResponse, err error)
	StartTask(cmd *commands.StartTask) (resp *commands.StartTaskResponse, err error)
	StopTask(cmd *commands.StopTask) (resp *commands.StopTaskResponse, err error)
	ResumeTask(cmd *commands.ResumeTask) (resp *commands.ResumeTaskResponse, err error)
	MoveTask(cmd *commands.MoveTask) (resp *commands.MoveTaskResponse, err error)

	// Schedule Management
	CreateSchedule(cmd *commands.CreateSchedule) (resp *commands.CreateScheduleResponse, err error)
	ModifySchedule(cmd *commands.ModifySchedule) (resp *commands.ModifyScheduleResponse, err error)
	GetSchedules(cmd *commands.GetSchedules) (resp *commands.GetSchedulesResponse, err error)
	DeleteSchedule(cmd *commands.DeleteSchedule) (resp *commands.DeleteScheduleResponse, err error)

	// Alert Management
	CreateAlert(cmd *commands.CreateAlert) (resp *commands.CreateAlertResponse, err error)
	GetAlerts(cmd *commands.GetAlerts) (resp *commands.GetAlertsResponse, err error)
	ModifyAlert(cmd *commands.ModifyAlert) (resp *commands.ModifyAlertResponse, err error)
	DeleteAlert(cmd *commands.DeleteAlert) (resp *commands.DeleteAlertResponse, err error)
	TestAlert(cmd *commands.TestAlert) (resp *commands.TestAlertResponse, err error)

	// Report Management
	CreateReport(cmd *commands.CreateReport) (resp *commands.CreateReportResponse, err error)
	GetReports(cmd *commands.GetReports) (resp *commands.GetReportsResponse, err error)
	DeleteReport(cmd *commands.DeleteReport) (resp *commands.DeleteReportResponse, err error)
	CreateReportFormat(cmd *commands.CreateReportFormat) (resp *commands.CreateReportFormatResponse, err error)
	ModifyReportFormat(cmd *commands.ModifyReportFormat) (resp *commands.ModifyReportFormatResponse, err error)
	GetReportFormats(cmd *commands.GetReportFormats) (resp *commands.GetReportFormatsResponse, err error)
	DeleteReportFormat(cmd *commands.DeleteReportFormat) (resp *commands.DeleteReportFormatResponse, err error)
	VerifyReportFormat(cmd *commands.VerifyReportFormat) (resp *commands.VerifyReportFormatResponse, err error)
	CreateReportConfig(cmd *commands.CreateReportConfig) (resp *commands.CreateReportConfigResponse, err error)
	ModifyReportConfig(cmd *commands.ModifyReportConfig) (resp *commands.ModifyReportConfigResponse, err error)
	GetReportConfigs(cmd *commands.GetReportConfigs) (resp *commands.GetReportConfigsResponse, err error)
	DeleteReportConfig(cmd *commands.DeleteReportConfig) (resp *commands.DeleteReportConfigResponse, err error)
	GetSystemReports(cmd *commands.GetSystemReports) (resp *commands.GetSystemReportsResponse, err error)

	// Results & Vulnerabilities
	GetResults(cmd *commands.GetResults) (resp *commands.GetResultsResponse, err error)
	GetVulns(cmd *commands.GetVulns) (resp *commands.GetVulnsResponse, err error)

	// Notes, Tags, Filters, Tickets, Overrides
	CreateNote(cmd *commands.CreateNote) (resp *commands.CreateNoteResponse, err error)
	ModifyNote(cmd *commands.ModifyNote) (resp *commands.ModifyNoteResponse, err error)
	GetNotes(cmd *commands.GetNotes) (resp *commands.GetNotesResponse, err error)
	DeleteNote(cmd *commands.DeleteNote) (resp *commands.DeleteNoteResponse, err error)
	CreateTag(cmd *commands.CreateTag) (resp *commands.CreateTagResponse, err error)
	ModifyTag(cmd *commands.ModifyTag) (resp *commands.ModifyTagResponse, err error)
	GetTags(cmd *commands.GetTags) (resp *commands.GetTagsResponse, err error)
	DeleteTag(cmd *commands.DeleteTag) (resp *commands.DeleteTagResponse, err error)
	CreateFilter(cmd *commands.CreateFilter) (resp *commands.CreateFilterResponse, err error)
	ModifyFilter(cmd *commands.ModifyFilter) (resp *commands.ModifyFilterResponse, err error)
	GetFilters(cmd *commands.GetFilters) (resp *commands.GetFiltersResponse, err error)
	DeleteFilter(cmd *commands.DeleteFilter) (resp *commands.DeleteFilterResponse, err error)
	CreateTicket(cmd *commands.CreateTicket) (resp *commands.CreateTicketResponse, err error)
	ModifyTicket(cmd *commands.ModifyTicket) (resp *commands.ModifyTicketResponse, err error)
	GetTickets(cmd *commands.GetTickets) (resp *commands.GetTicketsResponse, err error)
	DeleteTicket(cmd *commands.DeleteTicket) (resp *commands.DeleteTicketResponse, err error)
	CreateOverride(cmd *commands.CreateOverride) (resp *commands.CreateOverrideResponse, err error)
	DeleteOverride(cmd *commands.DeleteOverride) (resp *commands.DeleteOverrideResponse, err error)
	GetOverrides(cmd *commands.GetOverrides) (resp *commands.GetOverridesResponse, err error)
	ModifyOverride(cmd *commands.ModifyOverride) (resp *commands.ModifyOverrideResponse, err error)

	// Configuration, Preferences, Settings
	GetConfigs(cmd *commands.GetConfigs) (resp *commands.GetConfigsResponse, err error)
	CreateConfig(cmd *commands.CreateConfig) (resp *commands.CreateConfigResponse, err error)
	ModifyConfig(cmd *commands.ModifyConfig) (resp *commands.ModifyConfigResponse, err error)
	DeleteConfig(cmd *commands.DeleteConfig) (resp *commands.DeleteConfigResponse, err error)
	SyncConfig(cmd *commands.SyncConfig) (resp *commands.SyncConfigResponse, err error)
	GetPreferences(cmd *commands.GetPreferences) (resp *commands.GetPreferencesResponse, err error)
	ModifySetting(cmd *commands.ModifySetting) (resp *commands.ModifySettingResponse, err error)
	GetSettings(cmd *commands.GetSettings) (resp *commands.GetSettingsResponse, err error)

	// Port Lists & Ranges
	CreatePortList(cmd *commands.CreatePortList) (resp *commands.CreatePortListResponse, err error)
	ModifyPortList(cmd *commands.ModifyPortList) (resp *commands.ModifyPortListResponse, err error)
	GetPortLists(cmd *commands.GetPortLists) (resp *commands.GetPortListsResponse, err error)
	DeletePortList(cmd *commands.DeletePortList) (resp *commands.DeletePortListResponse, err error)
	CreatePortRange(cmd *commands.CreatePortRange) (resp *commands.CreatePortRangeResponse, err error)
	DeletePortRange(cmd *commands.DeletePortRange) (resp *commands.DeletePortRangeResponse, err error)

	// Scanners
	CreateScanner(cmd *commands.CreateScanner) (resp *commands.CreateScannerResponse, err error)
	ModifyScanner(cmd *commands.ModifyScanner) (resp *commands.ModifyScannerResponse, err error)
	GetScanners(cmd *commands.GetScanners) (resp *commands.GetScannersResponse, err error)
	DeleteScanner(cmd *commands.DeleteScanner) (resp *commands.DeleteScannerResponse, err error)
	VerifyScanner(cmd *commands.VerifyScanner) (resp *commands.VerifyScannerResponse, err error)

	// TLS Certificates
	CreateTLSCertificate(cmd *commands.CreateTLSCertificate) (resp *commands.CreateTLSCertificateResponse, err error)
	ModifyTLSCertificate(cmd *commands.ModifyTLSCertificate) (resp *commands.ModifyTLSCertificateResponse, err error)
	GetTLSCertificates(cmd *commands.GetTLSCertificates) (resp *commands.GetTLSCertificatesResponse, err error)

	// Agents
	ModifyAgents(cmd *commands.ModifyAgents) (resp *commands.ModifyAgentsResponse, err error)
	GetAgents(cmd *commands.GetAgents) (resp *commands.GetAgentsResponse, err error)
	DeleteAgents(cmd *commands.DeleteAgents) (resp *commands.DeleteAgentsResponse, err error)

	// Feeds, Licenses, Features, Aggregates, Resource Names
	GetNVTs(cmd *commands.GetNVTs) (resp *commands.GetNVTsResponse, err error)
	GetNVTFamilies(cmd *commands.GetNVTFamilies) (resp *commands.GetNVTFamiliesResponse, err error)
	GetFeeds(cmd *commands.GetFeeds) (resp *commands.GetFeedsResponse, err error)
	ModifyLicense(cmd *commands.ModifyLicense) (resp *commands.ModifyLicenseResponse, err error)
	GetLicense(cmd *commands.GetLicense) (resp *commands.GetLicenseResponse, err error)
	GetFeatures(cmd *commands.GetFeatures) (resp *commands.GetFeaturesResponse, err error)
	GetAggregates(cmd *commands.GetAggregates) (resp *commands.GetAggregatesResponse, err error)
	GetResourceNames(cmd *commands.GetResourceNames) (resp *commands.GetResourceNamesResponse, err error)

	// Miscellaneous
	GetInfo(cmd *commands.GetInfo) (resp *commands.GetInfoResponse, err error)
	GetVersion(cmd *commands.GetVersion) (resp *commands.GetVersionResponse, err error)
	Help(cmd *commands.Help) (resp *commands.HelpResponse, err error)
	EmptyTrashcan(cmd *commands.EmptyTrashcan) (resp *commands.EmptyTrashcanResponse, err error)
	Restore(cmd *commands.Restore) (resp *commands.RestoreResponse, err error)
	RunWizard(cmd *commands.RunWizard) (resp *commands.RunWizardResponse, err error)
	RawXML(xml string) (string, error)
}

type Connection

type Connection interface {
	Execute(command interface{}, response interface{}) error
	Close() error
	RawXML(xml string) (string, error)
}