graph-azure
Integrations are responsible for connecting to data provider APIs to collect
current state and maintain a graph database representing the entities and
relationships managed by the provider.
Development Environment
You may use use Node to execute directly on your machine.
Prerequisites:
- Install terraform and tfenv (see Development)
- Provide credentials in
.env
(see
Environment Variable)
Node:
- Install Node (Node Version Manager is recommended)
yarn install
yarn start:containers
yarn start
Activity is logged to the console indicating the operations produced and
processed. View raw data in the graph database using
Graphexp.
Execute the integration again to see that there are no change operations
produced.
Restart the graph server to clear the data when you want to run the integration
with no existing data.
yarn restart:containers
Environment Variables
Provider API configuration is specified by users when they install the
integration into their JupiterOne environment. Some integrations may also
require pre-shared secrets, used across all integration installations, which is
to be secured by JupiterOne and provided in the execution context.
Local execution requires the same configuration parameters for a development
provider account. tools/execute.ts
is the place to provide the parameters. The
execution script must not include any credentials, and it is important to make
it easy for other developers to execute the integration against their own
development provider account.
- Update
tools/execute.ts
to provide the properties required by the
executionHandler
function - Create a
.env
file to provide the environment variables transferred into
the properties
For example, given this execution script:
const integrationConfig = {
apiToken: process.env.MYPROVIDER_LOCAL_EXECUTION_API_TOKEN,
};
const invocationArgs = {
preSharedPrivateKey: process.env.MYPROVIDER_LOCAL_EXECUTION_PRIVATE_KEY,
};
Create a .env
file (this is .gitignore
'd):
MYPROVIDER_LOCAL_EXECUTION_API_TOKEN=abc123
MYPROVIDER_LOCAL_EXECUTION_PRIVATE_KEY='something\nreally\nlong'
SDK Variables
Environment variables can modify some aspects of the integration SDK behavior.
These may be added to your .env
with values to overrided the defaults listed
here.
GRAPH_DB_ENDPOINT
- "localhost"
Running tests
All tests must be written using Jest. Focus on testing provider API interactions
and conversion from provider data to entities and relationships.
To run tests locally:
yarn test
Deployment
Managed integrations are deployed into the JupiterOne infrastructure by staff
engineers using internal projects that declare a dependency on the open source
integration NPM package. The package will be published by the JupiterOne team.
Versioning this project
This project is versioned using auto.
Versioning and publishing to NPM are now handled via adding GitHub labels to
pull requests. The following labels should be used for this process:
For each pull request, the degree of change should be registered by applying the
appropriate label of patch, minor, or major. This allows the repository to keep
track of the highest degree of change since the last release. When ready to
publish to NPM, the PR should have both its appropriate patch, minor, or major
label applied as well as a release label. The release label will denote to the
system that we need to publish to NPM and will correctly version based on the
highest degree of change since the last release, package the project, and
publish it to NPM.