Neops Secure Gateway
Concepts
Role in the Neops Eco-System
The gateway acts as a single endpoint for all the Graphql Operations of a running Neops Backend Graphql API. It can be used to transform the schema that is served to the client, as well as to modify the data that is served to the client. This can be used to filter out sensitive data, or to restrict the operations that the client can perform. Typically it is used to expose / restrict the Graphql API from a secure network to an insecure network.
Big Picture
graph TD
%% Top-level: Public Network
subgraph Public_Insecure_Network["` **Public Network** `"]
E1[Neops Dashboard]
E2[Enterprise Integration]
E3[Process Monitoring]
end
%% Middle-layer: Secure Gateway with Restrictions
subgraph Secure_Gateway[""` **Secure Gateway** `""]
direction TB
G1[filter out credentials] ~~~ G2[deny certain task executions] ~~~ G3[deny reports executions] ~~~ G4[deny mutations]
G5[hide all device details] ~~~ G6[show certain facts] ~~~ G7[deny task execution] ~~~ G8[allow only check data]
end
%% Bottom-level: Managed Network
subgraph Corporate_Managed_Network[""` **Managed Network** `""]
C[Neops Backend GQL API]
end
%% Connections
Public_Insecure_Network --- Secure_Gateway
Secure_Gateway --- Corporate_Managed_Network
%% Apply Styles
classDef redBox stroke:#FF0000,stroke-width:2px;
classDef blueBox stroke:#0000FF,stroke-width:2px;
classDef greenBox stroke:#008000,stroke-width:2px;
class E1,E2,E3 redBox;
class G1,G2,G3,G4,G5,G6,G7,G8 blueBox;
class C greenBox;
Features
Context of all features is the gateway acting as endpoint for all Graphql Operations within insecure networks to prevent 3rd party systems of accessing sensitive data, start processes and run reports or accessing device credentials.
Schema transformation
Having the ability to transform the schema that is served to the client, allows to restrict the operations that the client can perform.
A Graphql Operation is a query, mutation or subscription. The schema transformation can be used to allow or deny specific operations. It is possible to configure a list of allowed and denied operations. If a operation is allowed, all other operations are denied. If a operation is denied, all other operations are allowed.
See below for an example configuration.
Data transformation / Resolvers
Schema Transformations modify the schema that is served to the client. Resolvers affect the data that is served to the client during runtime of the Graphql Operation. This can be used to filter out sensitive data, or to restrict the operations that the client can perform according to configured rules.
See below for an example configuration.
Task and Report filtering
To ensure certain Tasks or Export can not be called, the gateway can be configured to allow or deny specific tasks and reports. Reports / Task filters are a specialized form of the Resolvers and act during runtime of the Graphql Operation and permit or deny the execution of specific tasks or reports the client is requesting to do so.
Configuration
Environment variables
Ensure to set the following environment variables (the values here are just examples) for the environemnt you are running the gateway in:
PORT=1234
PATH_TO_RULES=config/example-rules.json
GRAPHQL_ENDPOINT_NEOPS=http://localhost:8000/graphql
STATIC_AUTH_TOKEN="Bearer your-token"
Configuration Rules
Schema transformation
check the example file under config/example-rules.json to see how to configure the rules for the gateway.
To modify/transform the schema itself prior to serve the graphql endpoint, one can allow or deny certain operations. This directly modifies the schema which will be served to accessing clients.
operationAllow will allow the execution of specific operations by the client and deny all others. An empty list, will ALLOW all operations.
operationDeny will deny the execution of specific operations by the client.
Example:
{
"transformers": {
"operationAllow": [],
"operationDeny": [
{ "operationName": "Query", "fieldName": "interfacesElastic" }
]
}
}
Data transformation / Resolvers
Configuring resolvers gives ou access to the data that is served by the gateway.
valueErasers will remove the value (set to null) of a field from the response. This is useful for sensitive data that should not be exposed to the client.
tasksAllow will allow the execution of specific tasks by the client and deny all others. An empty list, will DENY all tasks.
tasksDeny will deny the execution of specific tasks by the client.
reportsAllow will allow the execution of specific reports by the client and deny all others. An empty list, will DENY all reports.
reportsDeny will deny the execution of specific reports by the client.
jsonData will allow or deny the population of specific json attributes of a specific field in the response. it can be an array of strings which represent json strings like ["config.version", "config.user"] or a regex path which describes allowed or denied object or array structures. See example below.
Example:
{
"transformers": {
"operationAllow": [],
"operationDeny": [
{ "operationName": "Query", "fieldName": "interfacesElastic" }
]
},
"resolvers": {
"valueErasers": [
{
"fieldName": "username",
"typeName": "DeviceType"
},
{
"fieldName": "hostname",
"typeName": "DeviceType"
}
],
"jsonData": [
{
"typeName": "DeviceType",
"fieldName": "checks",
"allow": ["device.available"],
"deny": null
},
{
"typeName": "DeviceType",
"fieldName": "facts",
"allow": "^location\\.devices\\[\\d+\\]\\.interfaces\\[\\d+\\]\\.name$",
"deny": null
}
],
"tasksAllow": null,
"tasksDeny": [],
"reportsAllow": [
{
"uniqueTaskName": "super.awesome.report"
}
],
"reportsDeny": [
{
"uniqueTaskName": "super.awesome.report"
}
]
}
}
to use the rules then in a docker container, you need to mount the file to the container: