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.
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.
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.
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.
|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:
|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
|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
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
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
|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.|