Documentation
¶
Overview ¶
Package server Amass Engine API.
@title Amass Engine API (v1) @version 1.0 @description HTTP API for managing Amass Engine sessions and submitting Open Asset Model (OAM) assets. @description Create a session with an engine config, query session stats/scope, and ingest typed OAM assets (single or bulk). @description Includes a WebSocket endpoint for streaming session logs. @termsOfService https://owasp.org/www-project-amass/
@contact.name OWASP Amass Project @contact.url https://github.com/owasp-amass/amass
@license.name Apache 2.0 @license.url https://www.apache.org/licenses/LICENSE-2.0
@BasePath /api/v1
@tag.name system @tag.description System endpoints (health, etc.) @tag.name sessions @tag.description Create, list, inspect, and terminate engine sessions. @tag.name scope @tag.description Read-only access to the scoped assets loaded into a session. @tag.name assets @tag.description Submit typed OAM assets to a session (single or bulk). @tag.name ws @tag.description WebSocket endpoints (e.g., session log streaming).
Index ¶
- Variables
- type AddAssetResponse
- type BulkAddAssetsRequest
- type BulkAddAssetsResponse
- type CreateSessionResponse
- type ErrorResponse
- type HealthCheckResponse
- type ListSessionsResponse
- type ScopeResponse
- type SessionStatsResponse
- type V1Handlers
- func (v *V1Handlers) AddAssetTypedHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) AddAssetsBulkHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) CreateSessionHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) GetScopeHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) GetStatsHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) HealthCheck(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) ListSessionsHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) PutAsset(ctx context.Context, sess et.Session, asset oam.Asset) (string, error)
- func (v *V1Handlers) PutAssets(ctx context.Context, sess et.Session, assets []oam.Asset) (int64, error)
- func (v *V1Handlers) TerminateSessionHandler(w http.ResponseWriter, r *http.Request)
- func (v *V1Handlers) WSLogsHandler(w http.ResponseWriter, r *http.Request)
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("not found") ErrBadRequest = errors.New("bad request") )
Functions ¶
This section is empty.
Types ¶
type AddAssetResponse ¶
type AddAssetResponse struct {
EntityID string `json:"entityID"`
}
type BulkAddAssetsRequest ¶
type BulkAddAssetsRequest struct {
Items []json.RawMessage `json:"items"`
}
Bulk typed add: {"items":[ <OAM obj>, <OAM obj>, ... ]} where each item is arbitrary JSON object without "type".
type BulkAddAssetsResponse ¶
type CreateSessionResponse ¶
type CreateSessionResponse struct {
SessionToken string `json:"sessionToken"`
}
type ErrorResponse ¶
type HealthCheckResponse ¶
type HealthCheckResponse struct {
Result string `json:"result"`
}
type ListSessionsResponse ¶
type ListSessionsResponse struct {
SessionTokens []string `json:"sessionTokens"`
}
type ScopeResponse ¶
type ScopeResponse struct {
Data []json.RawMessage `json:"data"`
}
type SessionStatsResponse ¶
type V1Handlers ¶
type V1Handlers struct {
// contains filtered or unexported fields
}
func NewV1Handlers ¶
func NewV1Handlers(ctx context.Context, dis et.Dispatcher, mgr et.SessionManager, log *slog.Logger) (*V1Handlers, error)
func (*V1Handlers) AddAssetTypedHandler ¶
func (v *V1Handlers) AddAssetTypedHandler(w http.ResponseWriter, r *http.Request)
AddAssetTypedHandler godoc
@Summary Add a single asset (typed by path) @Description Submits a single OAM asset to the session. The asset type is provided in the URL path; the request body is a raw OAM JSON object without a 'type' field. @Tags assets @Accept json @Produce json @Param session_token path string true "Session token (UUID)" @Param asset_type path string true "Asset type (e.g., autonomous_system, fqdn, ipaddress, netblock, location, organization)" @Param asset body json.RawMessage true "Raw OAM JSON object (without 'type')" @Success 200 {object} AddAssetResponse @Failure 400 {object} ErrorResponse "Invalid session token, invalid JSON, or invalid asset object" @Failure 404 {object} ErrorResponse "Session not found" @Failure 500 {object} ErrorResponse "Failed to submit the asset" @Router /sessions/{session_token}/assets/{asset_type} [post]
func (*V1Handlers) AddAssetsBulkHandler ¶
func (v *V1Handlers) AddAssetsBulkHandler(w http.ResponseWriter, r *http.Request)
AddAssetsBulkHandler godoc
@Summary Add assets in bulk (typed by path) @Description Submits multiple OAM assets to the session in one request. The asset type is provided in the URL path. Each item in 'items' is a raw OAM JSON object without a 'type' field. @Tags assets @Accept json @Produce json @Param session_token path string true "Session token (UUID)" @Param asset_type path string true "Asset type (e.g., autonomous_system, fqdn, ipaddress, netblock, location, organization)" @Param request body BulkAddAssetsRequest true "Bulk add request payload" @Success 200 {object} BulkAddAssetsResponse @Failure 400 {object} ErrorResponse "Invalid session token, invalid JSON, empty items, or no valid items" @Failure 404 {object} ErrorResponse "Session not found" @Failure 413 {object} ErrorResponse "Too many items in bulk request" @Failure 500 {object} BulkAddAssetsResponse "Server failure (response includes ingested/stored/failed)" @Router /sessions/{session_token}/assets/{asset_type}:bulk [post]
func (*V1Handlers) CreateSessionHandler ¶
func (v *V1Handlers) CreateSessionHandler(w http.ResponseWriter, r *http.Request)
CreateSessionHandler godoc
@Summary Create a new engine session @Description Creates a new Amass engine session using the provided configuration JSON. @Tags sessions @Accept json @Produce json @Param config body config.Config true "Engine configuration" @Success 201 {object} CreateSessionResponse @Failure 400 {object} ErrorResponse "Invalid JSON or invalid configuration" @Failure 500 {object} ErrorResponse "Failed to create session" @Router /sessions [post]
func (*V1Handlers) GetScopeHandler ¶
func (v *V1Handlers) GetScopeHandler(w http.ResponseWriter, r *http.Request)
GetScopeHandler godoc
@Summary Get session scope for an asset type @Description Returns the scoped assets for the given session and asset type as an array of raw OAM JSON objects. @Tags scope @Produce json @Param session_token path string true "Session token (UUID)" @Param asset_type path string true "Asset type (e.g., autonomoussystem, fqdn, ipaddress, netblock, location, organization)" @Success 200 {object} ScopeResponse "Response contains a 'data' array of raw OAM JSON" @Failure 400 {object} ErrorResponse "Invalid session token" @Failure 404 {object} ErrorResponse "Session not found or scope not found for asset type" @Router /sessions/{session_token}/scope/{asset_type} [get]
func (*V1Handlers) GetStatsHandler ¶
func (v *V1Handlers) GetStatsHandler(w http.ResponseWriter, r *http.Request)
GetStatsHandler godoc
@Summary Get session statistics @Description Returns the current runtime statistics for a session. @Tags sessions @Produce json @Param session_token path string true "Session token (UUID)" @Success 200 {object} SessionStatsResponse @Failure 400 {object} ErrorResponse "Invalid session token" @Failure 404 {object} ErrorResponse "Session not found" @Router /sessions/{session_token}/stats [get]
func (*V1Handlers) HealthCheck ¶
func (v *V1Handlers) HealthCheck(w http.ResponseWriter, r *http.Request)
HealthCheck godoc
@Summary Health check @Description Returns a simple health indicator that the Amass Engine API is running. @Tags system @Produce json @Success 200 {object} HealthCheckResponse @Router /health [get]
func (*V1Handlers) ListSessionsHandler ¶
func (v *V1Handlers) ListSessionsHandler(w http.ResponseWriter, r *http.Request)
ListSessionsHandler godoc
@Summary List active sessions @Description Returns the session tokens for all currently active sessions. @Tags sessions @Produce json @Success 200 {object} ListSessionsResponse @Failure 404 {object} ErrorResponse "Zero sessions found" @Router /sessions/list [get]
func (*V1Handlers) TerminateSessionHandler ¶
func (v *V1Handlers) TerminateSessionHandler(w http.ResponseWriter, r *http.Request)
TerminateSessionHandler godoc
@Summary Terminate a session @Description Cancels an active session. Returns no content on success. @Tags sessions @Param session_token path string true "Session token (UUID)" @Success 204 @Failure 400 {object} ErrorResponse "Invalid session token" @Failure 404 {object} ErrorResponse "Session not found" @Router /sessions/{session_token} [delete]
func (*V1Handlers) WSLogsHandler ¶
func (v *V1Handlers) WSLogsHandler(w http.ResponseWriter, r *http.Request)
WSLogsHandler godoc
@Summary Stream session logs (WebSocket) @Description Upgrades the HTTP connection to a WebSocket and streams session log lines as UTF-8 text frames. @Description The server sends periodic ping frames (~30s) and expects pong responses; idle connections may be closed. @Tags sessions @Param session_token path string true "Session token (UUID)" @Success 101 "Switching Protocols (WebSocket upgrade)" @Failure 400 {object} ErrorResponse "Invalid session token" @Failure 404 {object} ErrorResponse "Session not found" @Router /sessions/{session_token}/ws/logs [get] @Header 101 {string} Upgrade "websocket" @Header 101 {string} Connection "Upgrade"
Source Files