GraphQL

Database is accessible through a GraphQL API which uses JWT tokens as an Authentication mechanism or the specified X-Hasura-Access-Key in the .env file (careful this is a master key).

JWT Request

To generate a JWT access token you need to:

1. send a POST request on /api/auth/login/credentials endpoint to get a session ID. (note: you can also use LDAP for this, the process is similar on endpoint /api/auth/login/ldap)
2. send a POST request on /api/auth/jwt endpoint to get the token.

The login POST request should include username and password of the user that wants to access the API. Depending on the role of the user permissions are different.

Example of a curl login request (-k is for self-signed certificates):

curl -k -X POST -H "Content-Type: application/json" -H "x-artemis-api-key: $API_KEY" -d "{\"email\":\"$user_email\",\"password\":\"$user_password\"}" https://$url/api/auth/login/credentials

Note that the $API_KEY is the one you define in your environment (secret). The rest of the variables are also local ($user_email, $user_password, $url).

Successful request reply (200 status code):

{"user":{"_id":"...","name":"...","email":"...","role":"...","lastLogin":"...","sessionId":"..."}}

Keep the sessionID value. You will need it to request the JWT and then logout.

Example of a curl JWT request (-k is for self-signed certificates):

curl -k -X GET -H "Content-Type: application/json" -H "x-artemis-api-key: $API_KEY" -H "Cookie: sid=$sessionID" https://$url/api/auth/jwt

Successful request reply (200 status code):

{"access_token": "xxxxxxxxx"}

You can optionally logout to invalidate the session (note though that the access token will remain until it expires):

curl -k -X DELETE -H "Content-Type: application/json" -H "x-artemis-api-key: $API_KEY" -H "Cookie: sid=$sessionID" https://$url/api/auth/logout

Querying GraphQL

You can access the GraphQL API endpoint at /api/graphql. The schemas are auto-generated by Hasura so you can read their documentation on how to create queries for our database.

Examples

Query on bgp_updates table for all fields:

curl -k -X POST -H "Content-Type: application/json" -H "Authorization":"Bearer "$access_token https://$url/api/graphql -d @query.json

Where query.json file includes:

{
"query":
"query {
  view_bgpupdates(limit: 10, order_by: {timestamp: desc}) {
    as_path
    communities
    handled
    hijack_key
    matched_prefix
    orig_path
    origin_as
    peer_asn
    prefix
    service
    timestamp
    type
  }
}"
}

Query on hijacks table for all fields:

curl -k -X POST -H "Content-Type: application/json" -H "Authorization":"Bearer "$access_token https://$url/api/graphql -d @query.json

Where query.json file includes:

{
"query":
"query {
  view_hijacks(limit: 10, order_by: {time_last: desc}) {
    active
    comment
    configured_prefix
    hijack_as
    ignored
    dormant
    key
    mitigation_started
    num_asns_inf
    num_peers_seen
    outdated
    peers_seen
    peers_withdrawn
    prefix
    resolved
    seen
    time_detected
    time_ended
    time_last
    time_started
    timestamp_of_config
    type
    under_mitigation
    withdrawn
    community_annotation
    rpki_status
  }
}"
}

For subscriptions you need to use WebSockets.

GraphQL Console

You can enable GraphQL console in .env by setting HASURA_CONSOLE to true. Afterwards, you should configure nginx.conf to proxy to the console on a specific port and docker-compose.yaml to map the nginx container port to the supervisors.

Changes in nginx.conf to proxy hasura console to port 32000:

    server {
        listen 32000 ssl;
        resolver localhost;
        error_page 497  https://$host:$server_port$request_uri;

        location / {
            proxy_pass http://graphql:8080/;
            proxy_redirect off;
            proxy_http_version 1.1;
            proxy_set_header Host $host:$server_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header X-Forwarded-Ssl on;
        }

        ssl_certificate /etc/nginx/certs/cert.pem;
        ssl_certificate_key /etc/nginx/certs/key.pem;

        gzip on;
        gzip_proxied any;
        gzip_types
            text/css
            text/javascript
            text/xml
            text/plain
            application/javascript
            application/x-javascript
            application/json;
    }

Changes to docker-compose.yaml to map port and make it accessible.

            - 32000
        ports:
            - "80:80"
            - "443:443"
            - "32000:32000"

After these changes you can connect to the console using the X-Hasura-Access-Key when prompt. There you can generate your queries that you are going to use and mess around with the table definitions.