NAV Navbar
java pyton

Introduction

Welcome to the blockbird.data SDK documentation!

Blockbird.data enables a user to flag sensitive data on their database and then monitor user accesses to that data from within the application. Our SDK is used within your application's code to send information about these accesses to our API so your customers can view and analyze their users behaviour.

Onboarding

New users must create an account on our website. Our monitoring is applied to your Applications, which have one or more databases or services containing personal information.

Addding an Application

Step 1: The first step in on-boarding is to register your application on our dashboard by providing an Application name and Language. We understand that some applications are written in mutliple languages, so we ask that you provide most prominent backend language that performs the connection the your database. This helps us provide you with the correct SDK.

Identifying sensitive tables in your database

Step 2: We connect to your primary database to tag tables and columns which contain personal data. We only access the database schema, not the underlying data. From here, the user selects the tables that they would like to monitor for accesses. In order to identify the tables that contain sensitive data or personally identifiable information (PII), blockbird.data connects to your database and reads the table names and column names. This allows a user to select the tables and columns on their database that contains PII. Blockbird.data does not store the login credentials or the any database information. Nor does blockbird.data access any data from within the database, we only access the database schema, not the database that stores real data.

Some clients may wish to create a view only user account and grant permissions to only access the information_schema from the database.

There are various options for securing a connection to your database, including IP whitelisting, SSL, SSH, PKI and Kerberos authenication. Blockbird data will work with you on the procedure that best meets your security requirements. Once the on-boarding process is complete, the network access can be closed as we do not connect to your database again, unless you wish to add or edit the mapping.

When connected to your database, we ask the user to select both the tables and columns that contain sensitive information. You can rename these attributes to make them more user friendly to non-technical team members. Upon completion, you will be given a Database Key and Database Secret which you will need when setting up the SDK to send data to blockbird.data.

Database Key and Secret

Sending access information from your Application to blockbird.data

Once you have set up your account and mapped your sensitive tables, you must place some code in your application to communicate with our API.

Base URL

https://api-staging.blockbird.ventures

Adding the SDK to your codebase

<dependencies>
  ...
  <!-- Blockbird data additions -->
  <dependency>
      <groupId>ventures.blockbird.data</groupId>
      <artifactId>data-blockbird-sdk</artifactId>
      <version>0.1-SNAPSHOT</version>
  </dependency>
</dependencies>

Implementing the Blockbird SDK in your Application

Athenticate with blockbird.dataBlockbird API


import ventures.blockbird.data.BlockbirdAudit;

// add Blockbird Audit
BlockbirdAudit bbAudit = BlockbirdAudit.getInstance(
  apiUrl, 
  databaseKey,
  databaseSecret
);

Our API end-points are protected by a short-life ID Token that authenticates with each request. As part of the on-boarding, you will receive an Database Key and Database Secret which will be used to authenticate your requests. To authorize, you instantiate the BlockbirdAudit Object with the credentials that you received during onboarding.

SDK Parameters

Parameter Description
apiUrl the URL of the API
databaseKey the ID of your database on blockbird.data
databaseSecret your database Secret from blockbird.data

Data Access Queries

When a user accesses data on your application from your database, you can send this information to blockbird.data's API.

bbAudit.addQuery(user, group, table, columns, action, date, row_count)

To submit a query, you pass the following parameters to the method:

Parameter Required Type Description
user Yes String The unique ID of the user on your application
group Yes String The role(s) of the user on your application
table Yes String The Database Table in the query
columns Yes String[] The array of columns in the query
action Yes String Query peformed, one of CREATE, READ, UPDATE, DELETE
date Yes Date The time of the request
row_count Yes Number The number of rows returned, changed or deleted in the query

To reduce network traffic, queries are batched before sending to the API. If you wish to manually send the current batch at any time, you can call the run() method.

bbaudit.run();

This will send the current batch to blockbird.data's API.

Example of using SDK with Java Hibernate ORM

If your application uses the Hibernate framework to connect to your datebase, you can use an Interceptor to capture information on a users data accesses and send that information to our API. The EmptyInterceptor Object is an Abstract class that allows for application-defined custom interceptors. This object has a number of methods which can be capture informaion about the data that is being accessed or modified - these methods include onLoad(), onSave() and onDelete(). You can place the query submit function within these methods to capture data accesses and send them to our API.

Blockbird Data - System Architecture

System Architecture

Errors

Error Code Meaning
200 Success
400 Bad Request -- Your request sucks
401 Unauthorized -- Invalid Authorization header
404 Not Found -- The specified end-point was not found
500 Internal Server Error -- We had a problem with our server. Try again later.