docs

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Apr 9, 2026 License: MIT Imports: 2 Imported by: 0

README

Scanorama Documentation

Reference

File Description
CONFIGURATION.md Full configuration reference: every setting, environment variable, validation rule, hot-reload behaviour, and example configs for dev/staging/production
DEPLOYMENT.md Building from source, systemd service, database setup, security hardening, health endpoints, Prometheus scraping, troubleshooting

Planning

File Description
planning/ROADMAP.md Milestone roadmap: v0.23 (complete) through v1.0, feature scope, dependency graph, tool integrations reference

Technical

File Description
technical/architecture/system-overview.md Component diagram, package reference, external dependencies
technical/architecture/data-flow.md Request lifecycle, scan and discovery pipelines, WebSocket event flow, migration flow
technical/architecture/scheduling-flow.md Cron → job → scan → results state machine, concurrency model
technical/architecture/logging.md Logging, metrics, and worker pool architecture
technical/testing.md Test structure, running tests, writing DB and scanning tests, CI integration

API

The authoritative API reference is the live Swagger UI served by the backend:

http://localhost:8080/swagger/

The OpenAPI spec is generated from source annotations (swag generate) and lives in swagger/.

Documentation

Overview

Package docs provides Swagger documentation for the Scanorama API.

This file contains all API endpoint documentation using swaggo annotations. Run `swag init` to generate OpenAPI specification files.

IMPROVEMENTS: - Added operationId to all endpoints for proper client generation - Applied security definitions consistently - Added comprehensive error responses - Improved response coverage and documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AdminStatus 

func AdminStatus(_ http.ResponseWriter, _ *http.Request)

AdminStatus godoc @Summary Admin status @Description Returns administrative status information @Tags Admin @Produce json @Security ApiKeyAuth @Success 200 {object} AdminStatusResponse @Failure 401 {object} ErrorResponse @Failure 403 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /admin/status [get] @ID getAdminStatus

func CreateDiscoveryJob 

func CreateDiscoveryJob(_ http.ResponseWriter, _ *http.Request)

CreateDiscoveryJob godoc @Summary Create discovery job @Description Create a new network discovery job @Tags Discovery @Accept json @Produce json @Param discovery body CreateDiscoveryJobRequest true "Discovery job configuration" @Success 201 {object} DiscoveryJobResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /discovery [post] @ID createDiscoveryJob

func CreateGlobalExclusion added in v0.13.0 

func CreateGlobalExclusion(_ http.ResponseWriter, _ *http.Request)

CreateGlobalExclusion godoc @Summary Create global exclusion @Description Create a global exclusion rule that applies to all networks @Tags Exclusions @Accept json @Produce json @Param exclusion body CreateExclusionRequest true "Exclusion configuration" @Success 201 {object} NetworkExclusionResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /exclusions [post] @ID createGlobalExclusion

func CreateHost 

func CreateHost(_ http.ResponseWriter, _ *http.Request)

CreateHost godoc @Summary Create host @Description Manually add a host to the inventory @Tags Hosts @Accept json @Produce json @Param host body HostResponse true "Host information" @Success 201 {object} HostResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /hosts [post] @ID createHost

func CreateNetwork added in v0.13.0 

func CreateNetwork(_ http.ResponseWriter, _ *http.Request)

CreateNetwork godoc @Summary Create network @Description Create a new network for scanning and discovery @Tags Networks @Accept json @Produce json @Param network body CreateNetworkRequest true "Network configuration" @Success 201 {object} NetworkResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks [post] @ID createNetwork

func CreateNetworkExclusion added in v0.13.0 

func CreateNetworkExclusion(_ http.ResponseWriter, _ *http.Request)

CreateNetworkExclusion godoc @Summary Create network exclusion @Description Add an exclusion rule to a specific network @Tags Networks @Accept json @Produce json @Param networkId path string true "Network ID" format(uuid) @Param exclusion body CreateExclusionRequest true "Exclusion configuration" @Success 201 {object} NetworkExclusionResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/exclusions [post] @ID createNetworkExclusion

func CreateProfile 

func CreateProfile(_ http.ResponseWriter, _ *http.Request)

CreateProfile godoc @Summary Create profile @Description Create a new scan profile @Tags Profiles @Accept json @Produce json @Param profile body CreateProfileRequest true "Profile configuration" @Success 201 {object} ProfileResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /profiles [post] @ID createProfile

func CreateScan 

func CreateScan(_ http.ResponseWriter, _ *http.Request)

CreateScan godoc @Summary Create scan @Description Create a new network scan job @Tags Scans @Accept json @Produce json @Param scan body CreateScanRequest true "Scan configuration" @Success 201 {object} ScanResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans [post] @ID createScan

func CreateSchedule 

func CreateSchedule(_ http.ResponseWriter, _ *http.Request)

CreateSchedule godoc @Summary Create schedule @Description Create a new scheduled scan @Tags Schedules @Accept json @Produce json @Param schedule body CreateScheduleRequest true "Schedule configuration" @Success 201 {object} ScheduleResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules [post] @ID createSchedule

func DeleteExclusion added in v0.13.0 

func DeleteExclusion(_ http.ResponseWriter, _ *http.Request)

DeleteExclusion godoc @Summary Delete exclusion @Description Delete an exclusion rule by ID @Tags Exclusions @Param exclusionId path string true "Exclusion ID" format(uuid) @Success 204 "Successfully deleted" @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /exclusions/{exclusionId} [delete] @ID deleteExclusion

func DeleteHost 

func DeleteHost(_ http.ResponseWriter, _ *http.Request)

DeleteHost godoc @Summary Delete host @Description Remove host from inventory @Tags Hosts @Param hostId path string true "Host ID" format(uuid) @Success 204 "Successfully deleted" @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /hosts/{hostId} [delete] @ID deleteHost

func DeleteNetwork added in v0.13.0 

func DeleteNetwork(_ http.ResponseWriter, _ *http.Request)

DeleteNetwork godoc @Summary Delete network @Description Delete a network and its associated exclusions @Tags Networks @Param networkId path string true "Network ID" format(uuid) @Success 204 "Successfully deleted" @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId} [delete] @ID deleteNetwork

func DeleteProfile 

func DeleteProfile(_ http.ResponseWriter, _ *http.Request)

DeleteProfile godoc @Summary Delete profile @Description Delete scan profile @Tags Profiles @Param profileId path string true "Profile ID" format(uuid) @Success 204 "Successfully deleted" @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /profiles/{profileId} [delete] @ID deleteProfile

func DeleteScan 

func DeleteScan(_ http.ResponseWriter, _ *http.Request)

DeleteScan godoc @Summary Delete scan @Description Cancel running scan or delete completed scan @Tags Scans @Param scanId path string true "Scan ID" format(uuid) @Success 204 "Successfully deleted" @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans/{scanId} [delete] @ID deleteScan

func DeleteSchedule 

func DeleteSchedule(_ http.ResponseWriter, _ *http.Request)

DeleteSchedule godoc @Summary Delete schedule @Description Delete scheduled scan @Tags Schedules @Param scheduleId path string true "Schedule ID" format(uuid) @Success 204 "Successfully deleted" @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules/{scheduleId} [delete] @ID deleteSchedule

func DisableNetwork added in v0.13.0 

func DisableNetwork(_ http.ResponseWriter, _ *http.Request)

DisableNetwork godoc @Summary Disable network @Description Disable a network from scanning and discovery @Tags Networks @Produce json @Param networkId path string true "Network ID" format(uuid) @Success 200 {object} NetworkResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/disable [post] @ID disableNetwork

func DisableSchedule 

func DisableSchedule(_ http.ResponseWriter, _ *http.Request)

DisableSchedule godoc @Summary Disable schedule @Description Disable a scheduled scan @Tags Schedules @Produce json @Param scheduleId path string true "Schedule ID" format(uuid) @Success 200 {object} ScheduleResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules/{scheduleId}/disable [post] @ID disableSchedule

func EnableNetwork added in v0.13.0 

func EnableNetwork(_ http.ResponseWriter, _ *http.Request)

EnableNetwork godoc @Summary Enable network @Description Enable a network for scanning and discovery @Tags Networks @Produce json @Param networkId path string true "Network ID" format(uuid) @Success 200 {object} NetworkResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/enable [post] @ID enableNetwork

func EnableSchedule 

func EnableSchedule(_ http.ResponseWriter, _ *http.Request)

EnableSchedule godoc @Summary Enable schedule @Description Enable a scheduled scan @Tags Schedules @Produce json @Param scheduleId path string true "Schedule ID" format(uuid) @Success 200 {object} ScheduleResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules/{scheduleId}/enable [post] @ID enableSchedule

func GetDiscoveryJob 

func GetDiscoveryJob(_ http.ResponseWriter, _ *http.Request)

GetDiscoveryJob godoc @Summary Get discovery job @Description Get discovery job details by ID @Tags Discovery @Produce json @Param discoveryId path string true "Discovery Job ID" format(uuid) @Success 200 {object} DiscoveryJobResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /discovery/{discoveryId} [get] @ID getDiscoveryJob

func GetHost 

func GetHost(_ http.ResponseWriter, _ *http.Request)

GetHost godoc @Summary Get host @Description Get host details by ID @Tags Hosts @Produce json @Param hostId path string true "Host ID" format(uuid) @Success 200 {object} HostResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /hosts/{hostId} [get] @ID getHost

func GetHostScans 

func GetHostScans(_ http.ResponseWriter, _ *http.Request)

GetHostScans godoc @Summary Get host scans @Description Get scans associated with a specific host @Tags Hosts @Produce json @Param hostId path string true "Host ID" format(uuid) @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Success 200 {object} PaginatedScansResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /hosts/{hostId}/scans [get] @ID getHostScans

func GetNetwork added in v0.13.0 

func GetNetwork(_ http.ResponseWriter, _ *http.Request)

GetNetwork godoc @Summary Get network @Description Get network details by ID @Tags Networks @Produce json @Param networkId path string true "Network ID" format(uuid) @Success 200 {object} NetworkResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId} [get] @ID getNetwork

func GetNetworkStats added in v0.13.0 

func GetNetworkStats(_ http.ResponseWriter, _ *http.Request)

GetNetworkStats godoc @Summary Get network statistics @Description Returns aggregate statistics about networks, hosts, and exclusions @Tags Networks @Produce json @Success 200 {object} NetworkStatsResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/stats [get] @ID getNetworkStats

func GetProfile 

func GetProfile(_ http.ResponseWriter, _ *http.Request)

GetProfile godoc @Summary Get profile @Description Get scan profile details by ID @Tags Profiles @Produce json @Param profileId path string true "Profile ID" format(uuid) @Success 200 {object} ProfileResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /profiles/{profileId} [get] @ID getProfile

func GetScan 

func GetScan(_ http.ResponseWriter, _ *http.Request)

GetScan godoc @Summary Get scan @Description Get scan details by ID @Tags Scans @Produce json @Param scanId path string true "Scan ID" format(uuid) @Success 200 {object} ScanResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans/{scanId} [get] @ID getScan

func GetScanResults 

func GetScanResults(_ http.ResponseWriter, _ *http.Request)

GetScanResults godoc @Summary Get scan results @Description Get detailed results from a completed scan @Tags Scans @Produce json @Param scanId path string true "Scan ID" format(uuid) @Success 200 {object} map[string]interface{} @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans/{scanId}/results [get] @ID getScanResults

func GetSchedule 

func GetSchedule(_ http.ResponseWriter, _ *http.Request)

GetSchedule godoc @Summary Get schedule @Description Get schedule details by ID @Tags Schedules @Produce json @Param scheduleId path string true "Schedule ID" format(uuid) @Success 200 {object} ScheduleResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules/{scheduleId} [get] @ID getSchedule

func Health 

func Health(_ http.ResponseWriter, _ *http.Request)

Health godoc @Summary Health check @Description Returns service health status including database connectivity @Tags System @Produce json @Success 200 {object} HealthResponse @Success 503 {object} HealthResponse @Failure 429 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /health [get] @ID getHealth

func ListDiscoveryJobs 

func ListDiscoveryJobs(_ http.ResponseWriter, _ *http.Request)

ListDiscoveryJobs godoc @Summary List discovery jobs @Description Get paginated list of discovery jobs @Tags Discovery @Produce json @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Param status query string false "Filter by status" Enums(pending,running,completed,failed) @Success 200 {object} PaginatedDiscoveryJobsResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /discovery [get] @ID listDiscoveryJobs

func ListGlobalExclusions added in v0.13.0 

func ListGlobalExclusions(_ http.ResponseWriter, _ *http.Request)

ListGlobalExclusions godoc @Summary List global exclusions @Description Get all global exclusion rules not tied to a specific network @Tags Exclusions @Produce json @Success 200 {array} NetworkExclusionResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /exclusions [get] @ID listGlobalExclusions

func ListHosts 

func ListHosts(_ http.ResponseWriter, _ *http.Request)

ListHosts godoc @Summary List hosts @Description Get paginated list of discovered hosts with optional filtering @Tags Hosts @Produce json @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Param ip_address query string false "Filter by IP address" @Param hostname query string false "Filter by hostname" @Param status query string false "Filter by status" Enums(up,down,unknown) @Success 200 {object} PaginatedHostsResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /hosts [get] @ID listHosts

func ListNetworkDiscoveryJobs added in v0.20.0 

func ListNetworkDiscoveryJobs(_ http.ResponseWriter, _ *http.Request)

ListNetworkDiscoveryJobs godoc @Summary List discovery jobs for a network @Description Returns paginated history of discovery runs linked to the network, ordered most-recent first. @Tags Networks @Produce json @Param networkId path string true "Network ID" format(uuid) @Param page query int false "Page number (default 1)" @Param page_size query int false "Page size (default 50, max 100)" @Success 200 {object} PaginatedDiscoveryJobsResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 503 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/discovery [get] @ID listNetworkDiscoveryJobs

func ListNetworkExclusions added in v0.13.0 

func ListNetworkExclusions(_ http.ResponseWriter, _ *http.Request)

ListNetworkExclusions godoc @Summary List network exclusions @Description Get exclusion rules for a specific network @Tags Networks @Produce json @Param networkId path string true "Network ID" format(uuid) @Success 200 {array} NetworkExclusionResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/exclusions [get] @ID listNetworkExclusions

func ListNetworks added in v0.13.0 

func ListNetworks(_ http.ResponseWriter, _ *http.Request)

ListNetworks godoc @Summary List networks @Description Get paginated list of networks with optional filtering @Tags Networks @Produce json @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Param show_inactive query boolean false "Include inactive networks" @Param name query string false "Filter by network name" @Success 200 {object} PaginatedNetworksResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks [get] @ID listNetworks

func ListProfiles 

func ListProfiles(_ http.ResponseWriter, _ *http.Request)

ListProfiles godoc @Summary List profiles @Description Get paginated list of scan profiles @Tags Profiles @Produce json @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Param scan_type query string false "Filter by scan type" @Success 200 {object} PaginatedProfilesResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /profiles [get] @ID listProfiles

func ListScans 

func ListScans(_ http.ResponseWriter, _ *http.Request)

ListScans godoc @Summary List scans @Description Get paginated list of scans with optional filtering @Tags Scans @Produce json @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Param status query string false "Filter by status" Enums(pending,running,completed,failed,cancelled) @Param target query string false "Filter by target" @Success 200 {object} PaginatedScansResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans [get] @ID listScans

func ListSchedules 

func ListSchedules(_ http.ResponseWriter, _ *http.Request)

ListSchedules godoc @Summary List schedules @Description Get paginated list of scheduled scans @Tags Schedules @Produce json @Param page query int false "Page number" default(1) @Param page_size query int false "Items per page" default(20) @Param enabled query boolean false "Filter by enabled status" @Success 200 {object} PaginatedSchedulesResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules [get] @ID listSchedules

func Liveness added in v0.13.0 

func Liveness(_ http.ResponseWriter, _ *http.Request)

Liveness godoc @Summary Liveness check @Description Returns simple liveness status without dependency checks @Tags System @Produce json @Success 200 {object} LivenessResponse @Failure 500 {object} ErrorResponse @Router /liveness [get] @ID getLiveness

func Metrics 

func Metrics(_ http.ResponseWriter, _ *http.Request)

Metrics godoc @Summary Application metrics @Description Returns Prometheus metrics for monitoring @Tags System @Produce text/plain @Success 200 {string} string @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /metrics [get] @ID getMetrics

func RenameNetwork added in v0.13.0 

func RenameNetwork(_ http.ResponseWriter, _ *http.Request)

RenameNetwork godoc @Summary Rename network @Description Rename an existing network @Tags Networks @Accept json @Produce json @Param networkId path string true "Network ID" format(uuid) @Param rename body RenameNetworkRequest true "New network name" @Success 200 {object} NetworkResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/rename [put] @ID renameNetwork

func StartDiscovery 

func StartDiscovery(_ http.ResponseWriter, _ *http.Request)

StartDiscovery godoc @Summary Start discovery @Description Start a discovery job @Tags Discovery @Produce json @Param discoveryId path string true "Discovery Job ID" format(uuid) @Success 200 {object} DiscoveryJobResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /discovery/{discoveryId}/start [post] @ID startDiscovery

func StartNetworkDiscovery added in v0.20.0 

func StartNetworkDiscovery(_ http.ResponseWriter, _ *http.Request)

StartNetworkDiscovery godoc @Summary Start a discovery run for a network @Description Creates a discovery job linked to the network, immediately transitions it to running, and returns the job. If a discovery engine is configured the actual nmap scan executes asynchronously. @Tags Networks @Produce json @Param networkId path string true "Network ID" format(uuid) @Success 202 {object} DiscoveryJobResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Failure 503 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId}/discover [post] @ID startNetworkDiscovery

func StartScan 

func StartScan(_ http.ResponseWriter, _ *http.Request)

StartScan godoc @Summary Start scan @Description Start a pending scan @Tags Scans @Produce json @Param scanId path string true "Scan ID" format(uuid) @Success 200 {object} ScanResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans/{scanId}/start [post] @ID startScan

func Status 

func Status(_ http.ResponseWriter, _ *http.Request)

Status godoc @Summary System status @Description Returns detailed system status information @Tags System @Produce json @Success 200 {object} StatusResponse @Failure 429 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /status [get] @ID getStatus

func StopDiscovery 

func StopDiscovery(_ http.ResponseWriter, _ *http.Request)

StopDiscovery godoc @Summary Stop discovery @Description Stop a running discovery job @Tags Discovery @Produce json @Param discoveryId path string true "Discovery Job ID" format(uuid) @Success 200 {object} DiscoveryJobResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /discovery/{discoveryId}/stop [post] @ID stopDiscovery

func StopScan 

func StopScan(_ http.ResponseWriter, _ *http.Request)

StopScan godoc @Summary Stop scan @Description Stop a running scan @Tags Scans @Produce json @Param scanId path string true "Scan ID" format(uuid) @Success 200 {object} ScanResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 409 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans/{scanId}/stop [post] @ID stopScan

func UpdateHost 

func UpdateHost(_ http.ResponseWriter, _ *http.Request)

UpdateHost godoc @Summary Update host @Description Update host information @Tags Hosts @Accept json @Produce json @Param hostId path string true "Host ID" format(uuid) @Param host body HostResponse true "Updated host information" @Success 200 {object} HostResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /hosts/{hostId} [put] @ID updateHost

func UpdateNetwork added in v0.13.0 

func UpdateNetwork(_ http.ResponseWriter, _ *http.Request)

UpdateNetwork godoc @Summary Update network @Description Update network configuration @Tags Networks @Accept json @Produce json @Param networkId path string true "Network ID" format(uuid) @Param network body UpdateNetworkRequest true "Updated network configuration" @Success 200 {object} NetworkResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /networks/{networkId} [put] @ID updateNetwork

func UpdateProfile 

func UpdateProfile(_ http.ResponseWriter, _ *http.Request)

UpdateProfile godoc @Summary Update profile @Description Update scan profile configuration @Tags Profiles @Accept json @Produce json @Param profileId path string true "Profile ID" format(uuid) @Param profile body CreateProfileRequest true "Updated profile configuration" @Success 200 {object} ProfileResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /profiles/{profileId} [put] @ID updateProfile

func UpdateScan added in v0.13.0 

func UpdateScan(_ http.ResponseWriter, _ *http.Request)

UpdateScan godoc @Summary Update scan @Description Update an existing scan configuration @Tags Scans @Accept json @Produce json @Param scanId path string true "Scan ID" format(uuid) @Param scan body UpdateScanRequest true "Updated scan configuration" @Success 200 {object} ScanResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /scans/{scanId} [put] @ID updateScan

func UpdateSchedule 

func UpdateSchedule(_ http.ResponseWriter, _ *http.Request)

UpdateSchedule godoc @Summary Update schedule @Description Update schedule configuration @Tags Schedules @Accept json @Produce json @Param scheduleId path string true "Schedule ID" format(uuid) @Param schedule body CreateScheduleRequest true "Updated schedule configuration" @Success 200 {object} ScheduleResponse @Failure 400 {object} ErrorResponse @Failure 401 {object} ErrorResponse @Failure 404 {object} ErrorResponse @Failure 422 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Security ApiKeyAuth @Router /schedules/{scheduleId} [put] @ID updateSchedule

func Version 

func Version(_ http.ResponseWriter, _ *http.Request)

Version godoc @Summary Version information @Description Returns version and build information @Tags System @Produce json @Success 200 {object} VersionResponse @Failure 429 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /version [get] @ID getVersion

Types

type AdminStatusResponse 

type AdminStatusResponse struct {
	AdminStatus string                 `json:"admin_status" example:"active"`
	Timestamp   time.Time              `json:"timestamp"`
	ServerInfo  map[string]interface{} `json:"server_info"`
}

AdminStatusResponse represents administrative status

type CreateDiscoveryJobRequest 

type CreateDiscoveryJobRequest struct {
	Name        string   `json:"name" example:"Office Network Discovery"`
	Networks    []string `json:"networks" example:"192.168.1.0/24"`
	Method      string   `json:"method" example:"ping" enums:"ping,arp,icmp,tcp_connect"`
	Description string   `json:"description,omitempty"`
	Enabled     bool     `json:"enabled" example:"true"`
}

CreateDiscoveryJobRequest represents a request to create a discovery job

type CreateExclusionRequest added in v0.13.0 

type CreateExclusionRequest struct {
	ExcludedCIDR string  `json:"excluded_cidr" example:"192.168.1.128/25"`
	Reason       *string `json:"reason,omitempty" example:"Reserved for printers"`
}

CreateExclusionRequest represents a request to create a network exclusion

type CreateNetworkRequest added in v0.13.0 

type CreateNetworkRequest struct {
	Name            string  `json:"name" example:"Office Network"`
	CIDR            string  `json:"cidr" example:"192.168.1.0/24"`
	Description     *string `json:"description,omitempty" example:"Main office network"`
	DiscoveryMethod string  `json:"discovery_method" example:"ping" enums:"ping,tcp,arp,icmp"`
	IsActive        *bool   `json:"is_active,omitempty" example:"true"`
	ScanEnabled     *bool   `json:"scan_enabled,omitempty" example:"true"`
}

CreateNetworkRequest represents a request to create a network

type CreateProfileRequest 

type CreateProfileRequest struct {
	Name        string            `json:"name" example:"Custom Scan Profile"`
	Description string            `json:"description,omitempty" example:"Custom scan configuration"`
	ScanType    string            `json:"scan_type" example:"connect" enums:"connect,syn,ack,udp,aggressive,comprehensive"`
	Ports       string            `json:"ports,omitempty" example:"22,80,443,8080"`
	Options     map[string]string `json:"options,omitempty"`
}

CreateProfileRequest represents a request to create a scan profile

type CreateScanRequest 

type CreateScanRequest struct {
	Name        string            `json:"name" example:"Weekly security scan"`
	Targets     []string          `json:"targets" example:"192.168.1.0/24"`
	ScanType    string            `json:"scan_type" example:"connect" enums:"connect,syn,ack,udp,aggressive,comprehensive"`
	ProfileID   *string           `json:"profile_id,omitempty" example:"550e8400-e29b-41d4-a716-446655440001"`
	Description string            `json:"description,omitempty" example:"Regular security assessment"`
	Ports       string            `json:"ports,omitempty" example:"22,80,443"`
	Options     map[string]string `json:"options,omitempty"`
	OSDetection bool              `json:"os_detection,omitempty" example:"false"`
	Tags        []string          `json:"tags,omitempty"`
}

CreateScanRequest represents a request to create a new scan

type CreateScheduleRequest 

type CreateScheduleRequest struct {
	Name      string `json:"name" example:"Daily Security Scan"`
	CronExpr  string `json:"cron_expr" example:"0 2 * * *"`
	Type      string `json:"type" example:"scan" enums:"scan,discovery"`
	NetworkID string `json:"network_id" example:"550e8400-e29b-41d4-a716-446655440010"`
	Enabled   bool   `json:"enabled" example:"true"`
}

CreateScheduleRequest represents a request to create a schedule

type DiscoveryJobResponse 

type DiscoveryJobResponse struct {
	ID          string     `json:"id" example:"550e8400-e29b-41d4-a716-446655440004"`
	Name        string     `json:"name" example:"Network Discovery"`
	Description string     `json:"description,omitempty"`
	Networks    []string   `json:"networks" example:"192.168.1.0/24"`
	Method      string     `json:"method" example:"ping" enums:"ping,arp,icmp,tcp_connect"`
	Status      string     `json:"status" example:"running" enums:"pending,running,completed,failed"`
	Progress    float64    `json:"progress" example:"45.5"`
	HostsFound  int        `json:"hosts_found" example:"12"`
	Enabled     bool       `json:"enabled" example:"true"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	StartedAt   *time.Time `json:"started_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
	LastRun     *time.Time `json:"last_run,omitempty"`
	NextRun     *time.Time `json:"next_run,omitempty"`
	LastError   string     `json:"last_error,omitempty"`
	CreatedBy   string     `json:"created_by,omitempty"`
}

DiscoveryJobResponse represents a discovery job

type ErrorResponse 

type ErrorResponse struct {
	Error     string    `json:"error" example:"Invalid request"`
	Timestamp time.Time `json:"timestamp"`
	RequestID string    `json:"request_id,omitempty" example:"req-123"`
}

ErrorResponse represents an error response

type HealthResponse 

type HealthResponse struct {
	Status    string            `json:"status" example:"healthy"`
	Timestamp time.Time         `json:"timestamp"`
	Uptime    string            `json:"uptime" example:"2h30m45s"`
	Checks    map[string]string `json:"checks"`
}

HealthResponse represents health check response

type HostResponse 

type HostResponse struct {
	ID         string    `json:"id" example:"550e8400-e29b-41d4-a716-446655440002"`
	IPAddress  string    `json:"ip_address" example:"192.168.1.100"`
	Hostname   *string   `json:"hostname,omitempty" example:"server01.local"`
	MACAddress *string   `json:"mac_address,omitempty" example:"00:1B:44:11:3A:B7"`
	OpenPorts  []int     `json:"open_ports" example:"22,80,443"`
	Status     string    `json:"status" example:"up" enums:"up,down,unknown"`
	LastSeen   time.Time `json:"last_seen"`
	FirstSeen  time.Time `json:"first_seen"`
	ScanCount  int       `json:"scan_count" example:"5"`
}

HostResponse represents a discovered host

type LivenessResponse added in v0.13.0 

type LivenessResponse struct {
	Status    string    `json:"status" example:"alive"`
	Timestamp time.Time `json:"timestamp"`
	Uptime    string    `json:"uptime" example:"2h30m45s"`
}

LivenessResponse represents a liveness check response

type NetworkExclusionResponse added in v0.13.0 

type NetworkExclusionResponse struct {
	ID           string    `json:"id" example:"550e8400-e29b-41d4-a716-446655440011"`
	NetworkID    *string   `json:"network_id,omitempty" example:"550e8400-e29b-41d4-a716-446655440010"`
	ExcludedCIDR string    `json:"excluded_cidr" example:"192.168.1.128/25"`
	Reason       *string   `json:"reason,omitempty" example:"Reserved for printers"`
	Enabled      bool      `json:"enabled" example:"true"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
	CreatedBy    *string   `json:"created_by,omitempty" example:"admin"`
}

NetworkExclusionResponse represents a network exclusion rule

type NetworkResponse added in v0.13.0 

type NetworkResponse struct {
	ID                  string     `json:"id" example:"550e8400-e29b-41d4-a716-446655440010"`
	Name                string     `json:"name" example:"Office Network"`
	CIDR                string     `json:"cidr" example:"192.168.1.0/24"`
	Description         *string    `json:"description,omitempty" example:"Main office network"`
	DiscoveryMethod     string     `json:"discovery_method" example:"ping" enums:"ping,tcp,arp,icmp"`
	IsActive            bool       `json:"is_active" example:"true"`
	ScanEnabled         bool       `json:"scan_enabled" example:"true"`
	ScanIntervalSeconds int        `json:"scan_interval_seconds" example:"3600"`
	ScanPorts           string     `json:"scan_ports" example:"22,80,443,8080"`
	ScanType            string     `json:"scan_type" example:"connect" enums:"connect,syn,ack,udp,aggressive,comprehensive"`
	LastDiscovery       *time.Time `json:"last_discovery,omitempty"`
	LastScan            *time.Time `json:"last_scan,omitempty"`
	HostCount           int        `json:"host_count" example:"25"`
	ActiveHostCount     int        `json:"active_host_count" example:"20"`
	CreatedAt           time.Time  `json:"created_at"`
	UpdatedAt           time.Time  `json:"updated_at"`
	CreatedBy           *string    `json:"created_by,omitempty" example:"admin"`
	ModifiedBy          *string    `json:"modified_by,omitempty" example:"admin"`
}

NetworkResponse represents a network object

type NetworkStatsResponse added in v0.13.0 

type NetworkStatsResponse struct {
	Networks   map[string]interface{} `json:"networks"`
	Hosts      map[string]interface{} `json:"hosts"`
	Exclusions map[string]interface{} `json:"exclusions"`
}

NetworkStatsResponse represents network statistics

type PaginatedDiscoveryJobsResponse 

type PaginatedDiscoveryJobsResponse struct {
	Data       []DiscoveryJobResponse `json:"data"`
	Pagination PaginationInfo         `json:"pagination"`
}

PaginatedDiscoveryJobsResponse represents a paginated list of discovery jobs

type PaginatedHostsResponse 

type PaginatedHostsResponse struct {
	Data       []HostResponse `json:"data"`
	Pagination PaginationInfo `json:"pagination"`
}

PaginatedHostsResponse represents a paginated list of hosts

type PaginatedNetworksResponse added in v0.13.0 

type PaginatedNetworksResponse struct {
	Data       []NetworkResponse `json:"data"`
	Pagination PaginationInfo    `json:"pagination"`
}

PaginatedNetworksResponse represents a paginated list of networks

type PaginatedProfilesResponse 

type PaginatedProfilesResponse struct {
	Data       []ProfileResponse `json:"data"`
	Pagination PaginationInfo    `json:"pagination"`
}

PaginatedProfilesResponse represents a paginated list of profiles

type PaginatedScansResponse 

type PaginatedScansResponse struct {
	Data       []ScanResponse `json:"data"`
	Pagination PaginationInfo `json:"pagination"`
}

PaginatedScansResponse represents a paginated list of scans

type PaginatedSchedulesResponse 

type PaginatedSchedulesResponse struct {
	Data       []ScheduleResponse `json:"data"`
	Pagination PaginationInfo     `json:"pagination"`
}

PaginatedSchedulesResponse represents a paginated list of schedules

type PaginationInfo 

type PaginationInfo struct {
	Page       int `json:"page" example:"1"`
	PageSize   int `json:"page_size" example:"20"`
	TotalItems int `json:"total_items" example:"150"`
	TotalPages int `json:"total_pages" example:"8"`
}

PaginationInfo represents pagination metadata

type ProfileResponse 

type ProfileResponse struct {
	ID          string            `json:"id" example:"550e8400-e29b-41d4-a716-446655440003"`
	Name        string            `json:"name" example:"Quick Connect Scan"`
	Description string            `json:"description,omitempty" example:"Fast TCP connect scan"`
	ScanType    string            `json:"scan_type" example:"connect" enums:"connect,syn,ack,udp,aggressive,comprehensive"`
	Ports       string            `json:"ports,omitempty" example:"22,80,443"`
	Options     map[string]string `json:"options,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`
}

ProfileResponse represents a scan profile

type RenameNetworkRequest added in v0.13.0 

type RenameNetworkRequest struct {
	NewName string `json:"new_name" example:"New Office Network"`
}

RenameNetworkRequest represents a request to rename a network

type ScanResponse 

type ScanResponse struct {
	ID           string            `json:"id" example:"550e8400-e29b-41d4-a716-446655440000"`
	Name         string            `json:"name" example:"Ad-hoc scan: 192.168.1.0/24"`
	Description  string            `json:"description,omitempty"`
	ProfileID    *string           `json:"profile_id,omitempty" example:"550e8400-e29b-41d4-a716-446655440001"`
	ScanType     string            `json:"scan_type" example:"connect" enums:"connect,syn,ack,udp,aggressive,comprehensive"`
	Ports        string            `json:"ports,omitempty" example:"22,80,443"`
	Targets      []string          `json:"targets" example:"192.168.1.0/24"`
	Options      map[string]string `json:"options,omitempty"`
	Tags         []string          `json:"tags,omitempty"`
	Status       string            `json:"status" example:"running" enums:"pending,running,completed,failed"`
	Progress     float64           `json:"progress" example:"65.5"`
	CreatedAt    time.Time         `json:"created_at"`
	UpdatedAt    time.Time         `json:"updated_at"`
	StartedAt    *time.Time        `json:"started_at,omitempty"`
	CompletedAt  *time.Time        `json:"completed_at,omitempty"`
	Duration     *string           `json:"duration,omitempty" example:"14m30s"`
	PortsScanned *string           `json:"ports_scanned,omitempty" example:"443 open / 1200 total"`
	ErrorMessage *string           `json:"error_message,omitempty"`
	CreatedBy    string            `json:"created_by,omitempty"`
}

ScanResponse represents a scan object

type ScheduleResponse 

type ScheduleResponse struct {
	ID          string     `json:"id" example:"550e8400-e29b-41d4-a716-446655440005"`
	Name        string     `json:"name" example:"Weekly Security Scan"`
	Description string     `json:"description,omitempty"`
	CronExpr    string     `json:"cron_expr" example:"0 2 * * 1"`
	Type        string     `json:"type" example:"scan" enums:"scan,discovery"`
	NetworkID   string     `json:"network_id,omitempty" example:"550e8400-e29b-41d4-a716-446655440010"`
	NetworkName string     `json:"network_name,omitempty" example:"Office Network"`
	Enabled     bool       `json:"enabled" example:"true"`
	Status      string     `json:"status" example:"active"`
	LastRun     *time.Time `json:"last_run,omitempty"`
	NextRun     *time.Time `json:"next_run,omitempty"`
	RunCount    int        `json:"run_count" example:"5"`
	ErrorCount  int        `json:"error_count" example:"0"`
	LastError   string     `json:"last_error,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	CreatedBy   string     `json:"created_by,omitempty"`
}

ScheduleResponse represents a scheduled scan

type StatusResponse 

type StatusResponse struct {
	Service   string    `json:"service" example:"scanorama-api"`
	Version   string    `json:"version" example:"0.7.0"`
	Timestamp time.Time `json:"timestamp"`
	Uptime    string    `json:"uptime" example:"2h30m45s"`
}

StatusResponse represents system status response

type UpdateNetworkRequest added in v0.13.0 

type UpdateNetworkRequest struct {
	Name            *string `json:"name,omitempty" example:"Office Network"`
	CIDR            *string `json:"cidr,omitempty" example:"192.168.1.0/24"`
	Description     *string `json:"description,omitempty" example:"Main office network"`
	DiscoveryMethod *string `json:"discovery_method,omitempty" example:"ping" enums:"ping,tcp,arp,icmp"`
	IsActive        *bool   `json:"is_active,omitempty" example:"true"`
	ScanEnabled     *bool   `json:"scan_enabled,omitempty" example:"true"`
}

UpdateNetworkRequest represents a request to update a network

type UpdateScanRequest added in v0.13.0 

type UpdateScanRequest struct {
	Name        string            `json:"name" example:"Updated scan name"`
	Description string            `json:"description,omitempty" example:"Updated description"`
	Targets     []string          `json:"targets" example:"192.168.1.0/24"`
	ScanType    string            `json:"scan_type" example:"connect" enums:"connect,syn,ack,udp,aggressive,comprehensive"`
	Ports       string            `json:"ports,omitempty" example:"22,80,443"`
	ProfileID   *string           `json:"profile_id,omitempty"`
	Options     map[string]string `json:"options,omitempty"`
	Tags        []string          `json:"tags,omitempty"`
	OSDetection bool              `json:"os_detection,omitempty" example:"false"`
}

UpdateScanRequest represents a request to update an existing scan

type VersionResponse 

type VersionResponse struct {
	Version   string    `json:"version" example:"0.7.0"`
	Service   string    `json:"service" example:"scanorama"`
	Timestamp time.Time `json:"timestamp"`
}

VersionResponse represents version information

Source Files

View all Source files

Directories

Path Synopsis
Package swagger Code generated by swaggo/swag.
 Package swagger Code generated by swaggo/swag.

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.