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.