API

Available API's

You can use the REST API's below to retrieve details or execute commands.

The API's invoked with an HTTP POST expect a JSON body containing the specified parameters. Every POST API also supports an additional callChainUrls parameter containing a list of space-separated URL's used for call chaining.

Method Path Parameters Description
POST /api/dnslookup host Returns the results of a DNS lookup of the specified host name (or IP address).
POST /api/httprequest requestUrl, requestHostName, ignoreServerCertificateErrors Returns the results of an HTTP request for the specified URL (with an optional host name override).
POST /api/sqlconnection databaseType, sqlConnectionString, sqlConnectionStringSuffix, sqlQuery, useAzureManagedIdentity, azureManagedIdentityClientId Returns the results of the specified (scalar) SQL query against a given database. The databaseType can be SqlServer, PostgreSql, MySql, CosmosDB.
POST /api/azuremanagedidentity scopes, azureManagedIdentityClientId Returns an access token for the specified scopes on behalf of the managed identity representing your application (when running on a supported Azure service).
POST /api/socketconnection requestHostName, requestPort, requestBody, readResponse Returns the results of performing a raw TCP socket connection from the web server.
POST /api/processrun fileName, arguments, timeoutSeconds Returns the output of running a certain process on the host.
POST /api/spiffe workloadApiAddress, unixDomainSocketEndpoint, audience Returns the JWT-SVIDs from querying the local SPIFFE Workload API.
POST /api/healthcheck healthCheckMode, failNextNumberOfTimes Configures the health check endpoint. The healthCheckMode can be AlwaysSucceed, AlwaysFail or FailNextNumberOfTimes.
GET /api/introspector Returns all information from the inspector as a single response.
GET /api/introspector/<group> Returns only a single group (subset) of information from the inspector, e.g. only the Request group. Available groups: Request, HttpHeaders, Identity, Configuration, Environment, Application, System.
GET /api/introspector/<group>/<key> Returns the value of only a single key (and only the first if there are multiple values) from the inspector, e.g. only the Request ID part. See above for all available groups, and see the full inspector document for all available keys.
POST /api/introspector group, key Returns the requested information from the inspector (see above for group and key details).

Call Chaining

The main purpose for these API's is so that you can perform call chains of requests from one deployed instance of the application to one or more other instances. This makes it easy to set up a multi-tier test environment (e.g. on Kubernetes or other microservice platforms) and perform queries across multiple hops.

Imagine for example that you deploy a Kubernetes cluster with 4 pods, each of these running the exact same Inspector Gadget container. You can then add an info message or environment variable like tier to each pod indicating which tier they logically represent, e.g. front-end, api-gateway, api-1 and api-2. With that configuration in place, you can then perform a call chain to hop from the front-end to the api-gateway and from there to api-1.

For example, to validate that the tiers are able to reach each other (e.g. if you've deployed network policies or when you're using a service mesh), you can browse to the Inspector Gadget web page on the front-end, and from there perform an Introspector request by setting the "Call Chain" to "http://api-gateway http://api-1" (if those would be the URL's of the other pods of course). If you set the requested "Group" to Environment and the "Key" to tier (or whatever environment variable you picked), then you can see the simple value returned by each hop to show which tier it represents.

Note that this would work even if only the front-end is exposed externally, with the other tiers only accessible from within the cluster, because each call in the chain is done from the previous hop.