Configuring Graphistry

Administrators can add users, specify passwords, TLS/SSL, persist data across sessions, connect to databases, specify ontologies, and more.

For a list of many investigation-oriented options, see their settings reference page.
See update, backup, & migration instructions for preserving configurations and data across installations.
For advanced Python notebook and application configuration, see PyGraphistry configuration.

Add your team and provide API keys

See user creation docs

Top configuration places: data/config/custom.env, data/pivot-db/config/config.json

Graphistry is primarily configured through file data/config/custom.env
Connector, ontology, and pivot configuration is optionally via data/pivot-db/config/config.json. Many relevant options are detailed in a reference page.

Between edits, restart one or all Graphistry services: docker-compose stop and docker-compose up -d

Further configuration: docker-compose.yml and Caddyfile

More advanced administrators may edit docker-compose.yml . Maintenance is easier if you never edit it.
Custom TLS is via editing Caddyfile(Caddy docs), see below

SSO

Contact staff for setting up internal SSO (OIDC: Okta, ...) or via social logins to GitHub/Google

If using an external proxy or load balancer, configure Graphistry's site domain setting (see above) and check above TLS settings

Recommendations for SSO when self-hosting:

Setup email
Mark SSO as site-wide
Disallow non-SSO account creation
Decide whether SSO users can automatically join organizations without an invitation

TLS

We encourage everyone to use HTTPS over HTTP, especially through the automatic TLS option, for securing authentication

Graphistry supports both free automatic TLS within your server (Caddy/LetsEncrypt) and offloading to an external load balancer or proxy

As part of TLS configuration, decide whether to allow cross-origin embedding of private visualizations

TLS Hardening

Caddy

If Caddy is used for TLS, several additional policies may be of interest, but only use ones that match your intended usage patterns:

https://*.website.org:443 {
  ...
  reverse_proxy nginx:80 {
        # enable HSTS (1yr)
        header_down Strict-Transport-Security max-age=31536000;

        # disable clients from sniffing the media type
        header_down X-Content-Type-Options nosniff

        # clickjacking protection
        header_down X-Frame-Options SAMEORIGIN

        # keep referrer data off of HTTP connections
        header_down Referrer-Policy no-referrer-when-downgrade
  }
}

Note: Configuration line header_down X-Frame-Options SAMEORIGIN will prevent all cross-origin embedding. By default, public content can be cross-origin embedded while private content cannot. See also COOKIE_SAMESITE for enabling authorized private content in cross-origin embeddings.

Application servers

Also inform the Graphistry application servers to use secure cookies in data/config/custom.env:

COOKIE_SECURE=true

For visualizations to be embeddable in different origin sites, enable COOKIE_SECURE and then disable COOKIE_SAMESITE:

COOKIE_SAMESITE=None

... then restart: docker-compose up -d --force-recreate --no-deps nexus

Setup free Automatic TLS

Caddy supports free automatic TLS as long as your site meets the listed conditions.

Sample Caddyfile:

https://*.website.org:443 {
  tls {
    max_certs 100
  }
  respond /caddy/health/ 200 {
    body "{\"success\": true}"
    close
  }
  reverse_proxy nginx:80
}

Note that Graphistry is internally configured via nginx.

Setup free Semi-Automatic TLS

The above step may fail if your server does not allow outbound internet traffic. To work around, perform a manual LetsEncrypt Certbot handshake for Caddy.

Setup custom certs

If you already have certificates, Caddy can use them:

Place your certs in ./.caddy/my.crt and ./.caddy/my.key
Modify Caddyfile:

https://your.site.ngo:443 {
  tls /root/.caddy/my.crt /root/.caddy/my.key
  respond /caddy/health/ 200 {
    body "{\"success\": true}"
    close
  }
  reverse_proxy nginx:80
}

Note the use of a fully qualified domain name in the first line, and that the file paths are for the caddy container's file system, not the host file system

Setup offloading TLS from a load balancer or proxy

To enforce TLS using your own outside load balancer or proxy rather than the built-in Caddy server, we recommend:

Setup TLS at your load balancer (ex: AWS ALB) or proxy
Ensure http traffic is auto-upgraded (redirected) to https
Forward (stripped) http traffic to Graphistry
Optionally, in your Caddyfile's reverse_proxy section, add trusted_proxies so your load balancer's X-Forwarded-{For,Proto,Host} headers are trusted for propagation to Graphistry

IP List:

reverse_proxy 172.16.0.169:8080 {
	trusted_proxies 173.245.48.0/20 103.21.244.0/22
}

Shortcut for internal IPs:

reverse_proxy 172.16.0.169:8080 {
	trusted_proxies private_ranges
}

Debugging TLS

Custom TLS setups often fail due to the certificate, OS, network, Caddy config, and file permissions. To perform isolated checks on each, try:

Test the certificate
Test a standalone Caddy static file server
... Including on another box, if OS/network issues are suspected
Check the logs of docker-compose logs -f -t caddy nginx
Test whether the containers are up and ports match via docker-compose ps, curl, and curl from within a docker container (so within the docker network namespace)

If problems persist, please reach out to your Graphistry counterparts. Additional workarounds are possible.

Email

Optional

See the email section

Site domain

Optional

In the Admin portal, go to Sites and change the Domain name to your domain, such as graphs.acme-corp.com

This aids scenarios such as when using an outside proxy and ensuring that web users see the intended external domain instead of the internal one leaking through

Reverse proxy

Built-in proxying

Graphistry routes all public traffic through Docker container Caddy, so you generally modify Docker settings for service caddy: in docker-compose.yml (or data/config/custom.env) or Caddy settings in data/config/Caddyfile. Further internal proxying may occur, but we do not advise manipulating internal tiers.

External proxies

You may externally redirect traffic, such as through an AWS Load Balancer or CloudFlare

See above TLS discussion
Set the Site

Change public port

If 80 / 443 are already taken, such as when running multiple Graphistry instances on the same box, you may want to change to another port. For example, to expose public port 8888 for Graphistry's HTTP traffic instead of 80, configure docker-compose.yml to map it as follows:

  caddy:
    ...
    expose:
      - "8888"
    ports:
      - 8888:80

Reuse Graphistry reverse proxy and JWT auth as a bastion for other services

You can configure the Caddy service to also reverse proxy additional services, including requiring their users to log in with Graphistry account credentials.

For an example of both public and log-required proxies, see the graph-app-kit sample.

Dashboards

Separately configure the public and private dashboards

Connectors

Optionally, you can configure Graphistry to use database connectors. Graphistry will orchestrate cross-database query generation, pushing them down through the database API, and returning the combined results to the user. This means Graphistry can reuse your existing scaleout infrastructure and make its data more accessible to your users without requiring a second copy to be maintained. Some connectors further support use of the Graphistry data bridge for proxying requests between a Graphistry cloud server and an intermediate on-prem data bridge instead of directly connecting to on-prem API servers.

Security Notes

Graphistry only needs read only access to the database
Only one system-wide connector can be used per database per Graphistry virtual server at this time. Ex: You can have Splunk user 1 + Neo4j user 2 on one running Graphistry container, and Splunk user 3 + Neo4j user 2 on another running Graphistry container.
Templates and other embedding modes do not require further Graphistry configuration be beyond potentially API key generation. However, Graphistry implementors will still need access to external dashboards, APIs, etc., into which they'll be embedding Graphistry views.

Get started

Edit lines of data/config/custom.env corresponding to your connector and restart Graphistry (see .env for commented out examples):

ES_HOST=...
SPLUNK_HOST=...

Restart graphistry, or at least the pivot service:

docker-compose stop && docker-compose up -d or docker-compose stop nginx pivot && docker-compose up -d

Test

In /pivot/connectors, configured databases should appear in the live connectors section, and clicking the status check should turn them green
Running a sample investigation with a database query should return results

Example: Splunk

Create a restricted Splunk API user role from the Splunk Web UI

Settings -> Users -> Add new
Name: any, such as graphistry_role
For capabilities: rest_properties get, rtsearch, search
For indexes: Any that you want exposed to the investigtation team

Create a restricted Splunk API user from the Splunk Web UI

Settings -> Users -> Add new
Record their name/pwd
Assign them to the role graphistry_user from step 1

Configure Graphistry's custom.env with the Splunk server and user information:

### Required
SPLUNK_HOST=splunk.acme.org
SPLUNK_USER=admin
SPLUNK_KEY=...

### Optional
#SPLUNK_SCHEME=https
#SPLUNK_PORT=8089
#SPLUNK_WEB_PORT=443
#SPLUNK_SUFFIX=/en-US
#SPLUNK_CACHE_TIMEOUT=14400
#SPLUNK_SEARCH_MAX_TIME=20
#SPLUNK_USE_PROXY=false
#SPLUNK_PROXY_KEY=...
#SPLUNK_SERVER_KEY=...

Restart the pivot service (see Get Started) and test the connector as per above. You can test the underlying Splunk API configuration by running curl -u admin:changme https://splunk.host.name.here:8089/services/search/jobs/export -d search="search * | head 3" -d output_mode=csv from your local Splunk server and your Graphistry server.

Example: Neo4j

Configure Graphistry's data/pivot-db/config/config.json with the Neo4j server and user information:

{
    "neo4j": {
        "user": "neo4j",
        "password": "myneo4juser",
        "bolt": "bolt://my.neo4j.com:4687"
    }
}

For faster start, or to be explicit about schema, or avoid start issues, you may choose to skip schema inference and optionally provide your own:

{
    "neo4j": {
        "user": "neo4j",
        "password": "myneo4juser",
        "bolt": "bolt://my.neo4j.com:4687",
        "searchMaxTime": 5000,
        "schema": {
            "inferSchema": true,
            "labelProperties": {
                "MyLabel1": [ "my_field_1", "my_field_2" ],
                "MyLabel2": [ "my_field_1", "my_field_3" ],
                "MyLabel3": [ ]
            },
            "relationshipProperties": {
                "MY_RELN_1": [ "my_field_4" ],
                "MY_RELN_2": []
            },
            "defaultTimeIndex": {
                "nodeProperties": ["my_field2"]
            }
        }
    }
}

Restart the pivot service (see Get Started) and test the connector as per above. In-tool, you can test the connection status for the connector panel by clicking the 'check status' button for the Neo4j connector. If there is an error, you can further test your Neo4j database network connectivity by trying a Graphistry Jupyter notebook demo for Neo4j to connect to Neo4j from the notebook.

Data bridge

In scenarios such as a Graphistry cloud server accessing on-prem API servers, an intermediate on-prem data bridge may be necessary. You can mix bridged and direct (default) connectors in the same Graphistry server. Learn more about the Graphistry data bridge.

Variants

Give your Graphistry implementation user increased permissions so they can embed Graphistry into existing dashbboard and notification systems, such as for embedded visualizations and quicklinks into contextual investigation templates* Run a Graphistry data bridge, if available for your connector, which may help with cases such as firewalls preventing incoming connections from Graphistry to your database
Run a bastion server between Graphistry and your database, such as a new Splunk search head
Create fine-grained permissions by running multiple Graphistry virtual servers, with a new Splunk role per instance

Ontology

See custom ontology extensions and settings reference page for full options. Topics include controlling:

Map Column -> Type
Map Type -> color, icon, size
Map node/edge titles

Pivots

Every connector comes with a base set of pivots. See custom pivots for teaching Graphistry new pivots based on existing connectors and pivots.

Performance

See performance tuning

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

configure.md

configure.md

Configuring Graphistry

Add your team and provide API keys

Top configuration places: data/config/custom.env, data/pivot-db/config/config.json

Further configuration: docker-compose.yml and Caddyfile

SSO

TLS

TLS Hardening

Caddy

Application servers

Setup free Automatic TLS

Setup free Semi-Automatic TLS

Setup custom certs

Setup offloading TLS from a load balancer or proxy

Debugging TLS

Email

Site domain

Reverse proxy

Built-in proxying

External proxies

Change public port

Reuse Graphistry reverse proxy and JWT auth as a bastion for other services

Dashboards

Connectors

Security Notes

Get started

Example: Splunk

Example: Neo4j

Data bridge

Variants

Ontology

Pivots

Performance

Files

configure.md

Latest commit

History

configure.md

File metadata and controls

Configuring Graphistry

Add your team and provide API keys

Top configuration places: data/config/custom.env, data/pivot-db/config/config.json

Further configuration: docker-compose.yml and Caddyfile

SSO

TLS

TLS Hardening

Caddy

Application servers

Setup free Automatic TLS

Setup free Semi-Automatic TLS

Setup custom certs

Setup offloading TLS from a load balancer or proxy

Debugging TLS

Email

Site domain

Reverse proxy

Built-in proxying

External proxies

Change public port

Reuse Graphistry reverse proxy and JWT auth as a bastion for other services

Dashboards

Connectors

Security Notes

Get started

Example: Splunk

Example: Neo4j

Data bridge

Variants

Ontology

Pivots

Performance