Skip to content

You are viewing documentation for Immuta version 2021.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Audit HTTP API

Audience: Data Owners

Content Summary: The Audit API allows users to programmatically create Audit Records in Immuta.

Create Audit Record

Method Path Successful Status Code
POST /audit/createRecord 200

Request Path Parameters: General Details

  • profileId (integer): The profile ID for the user generating the action.
  • component (string): Required The Immuta component used to perform the action. Available options are
    • console
    • featureStore
    • dataSource
    • bim
    • audit
    • policy
    • project
    • plugin
    • governance
    • admin
    • tag
  • sqlUser (string): The database user account performing the action. This parameter should only be used if the action is being performed using a database user account.
  • dataSourceId (integer): The data source ID of the accessed data source. This parameter should only be used if the action is associated with a data source.
  • projectId (integer): The project ID of the project used to access the data source. This parameter should only be used if the action is associated with a project.
  • purposeIds (integer): The purpose ID of the purpose used to access the data source. This parameter should only be used if the action is associated with a purpose.
  • policyId (integer): The policy ID of the policy. This parameter should only be used if the action is associated with a Global Policy.

Request Path Parameters: Data Access

  • dataAccess (object): Describes access to an individual blob or a query that may grant access to data.
    • accessType (string): Indicates whether access was granted to an individual blob or if this was a query accessing data. Available options are
      • blob
      • query
    • blobId (string): The blob ID of the blob accesses. This parameter should be used when accessType equals blob.
    • query (string): The query used to access data. This parameter should only be used when accessType equals query.
    • dataSourceTableName (string): The data source table name that was queried.

Action Result

  • success (boolean): Required Denotes whether the action was successful.
  • failureReason (string): Describes the reason that the action failed. This parameter should only be used if success is false. Acceptable values are
    • systemError
    • insufficientAuthorizations
    • insufficientPermissions
    • userError
  • failureDetails (string): Additional details about the failed action. This parameter should only be used if success is false.

Record Details

  • recordType (string): Required The type of action being captured. Acceptable values are
    • auditQuery: anyone views, filters, or queries audit records in the Audit section of the UI.
    • blobFetch: a file is downloaded/viewed via the API.
    • blobIndex: a new file is discovered, either via API or scheduled crawl (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).
    • blobDelete: a file is removed from Immuta's index, either via API or scheduled crawl (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).
    • blobUpdateTags: a tag is added to a file, either via API or scheduled crawl (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).
    • spark: a query is executed via Spark.
    • sqlCreateUser: a Query Engine user account is created.
    • sqlDeleteUser: a Query Engine user account is deleted.
    • sqlResetPassword: a Query Engine user account password is reset.
    • sqlQuery: a query is executed via the Query Engine.
    • dataSourceCreate: a data source is created.
    • dataSourceDelete: a data source is disabled or deleted.
    • dataSourceExpired: a data source has expired.
    • dataSourceSave: a data source is updated.
    • dataSourceSubscription: a user is subscribed or unsubscribed from a data source.
    • dataSourceTestQuery: a health check query was run against the data source.
    • dictionaryCreate: a dictionary was created for a data source (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).
    • dictionaryDelete: a dictionary was deleted for a data source (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).
    • dictionaryUpdate: a dictionary was updated on a data source.
    • projectCreate: a project was created.
    • projectPurposeApprove: a project purpose was approved.
    • projectPurposeDeny: a project purpose was denied.
    • projectUpdate: a project was updated.
    • projectDelete: a project was disabled or deleted.
    • addToProject: a data source was added to a project.
    • removeFromProject: a data source was removed from a project.
    • projectSubscription: a user is subscribed or unsubscribed from a project.
    • acknowledgePurposes: a user acknowledged the purposes on a project.
    • accessUser: any change to a user's information (new attributes, groups, profile changes, or the user was disabled).
    • accessGroup: any change to a group.
    • apiKey: an API key was created or deleted or the metadata was queried.
    • tagAdded: a tag was added to a data source.
    • tagCreated: a user with GOVERNANCE permission created a new tag.
    • tagDeleted: a user with GOVERNANCE permission deleted a tag.
    • tagUpdated: a user with GOVERNANCE permission updated a tag.
    • tagRemoved: a tag was removed from a data source.
    • authenticate: a user logged in to Immuta.
    • checkPendingRequest: A user checked the status of a pending subscription request
    • policyExemption: if policies exemptions are enabled and the user meets a policy exemption, this record is created when querying for data.
    • purposeCreate: a user with GOVERNANCE or PROJECT_MANAGEMENT creates a new purpose.
    • purposeUpdate: a user with GOVERNANCE or PROJECT_MANAGEMENT updates a purpose.
    • purposeDelete: a user with GOVERNANCE or PROJECT_MANAGEMENT deletes a purpose.
    • licenseCreate: a new license key is added to Immuta.
    • licenseDelete: a license key is deleted.
    • policyAdjustmentCreate: a policy adjustment is created (policy adjustments must be enabled).
    • policyAdjustmentDelete: a policy adjustment is deleted (policy adjustments must be enabled).
    • policyAdjustmentExpired: a policy adjustment expires (policy adjustments must be enabled).
    • policyExport: policies are exported (policy import/export must be enabled).
    • policyImport: policies are imported (policy import/export must be enabled).
    • globalPolicyCertify: a global policy is marked as Certified.
    • policyCertificationExpired: a global policy certification expires.
    • globalPolicyCreate: a global policy is created.
    • globalPolicyUpdate: a global policy is updated.
    • globalPolicyDelete: a global policy is deleted.
    • globalPolicyDisabled: a user disabled a global policy on a specific data source.
    • globalPolicyApplied: a global policy was applied to a data source.
    • globalPolicyRemoved: a global policy was removed from a data source.
    • externalUserIdChanged: a user's external user id (for native integrations) was changed.
    • externalQuery: a query record that is allowed to be created by an external system to signify in Immuta audit that a query occurred.
    • unmaskRequest: A request was made to unmask a column masked with a reversible (or format preserving masking) policy.
    • queryDebugRequest: a request was made to download debug information for a query.
    • taskValidate: a new column or data source was marked as validated.
    • taskDelete: an unmask request or query debug request was deleted.
    • handleTask: an unmask request or query debug request was completed.
    • s3pBlobFetch: a file is downloaded/viewed via the S3 access pattern.
    • switchCurrentProject: the user switches the current project.
    • webhookCreate: a webhook was created.
    • webhookDelete: a webhook was deleted.
    • configurationUpdate: the system-wide configuration was updated.
    • driverUpload: an ODBC driver was uploaded.
    • workSpace: a user accessed a file inside of a workspace.
    • prestoQuery: a query was executed natively in Presto against an Immuta data source.
  • record (object): Describes the action being captured.
    • blobSize (integer): The size (in bytes) of the blob being fetched.
    • sqlUser (string): The username of the user whose access is being manipulated.
    • action (string): Denotes whether access was granted or revoked. Acceptable values are
      • revoked
      • granted
    • subscriptionState (string): Indicates the state to which the record was changed. Acceptable values are
      • denied
      • subscribed
      • expert
      • owner
      • ingest
      • unsubscribed
    • accessedId (integer): The user identifier of the user who is being acted upon.
    • accessedIdType (string): Type of user being acted upon. Acceptable values are
      • user
      • group
    • hardDelete (boolean): Denotes whether this was a hard delete.
    • expirationDate (datetime): Denotes when the action expired in Immuta.
    • accessType (string): Denotes how the specified user was accessed. Acceptable values are
      • update
      • get
      • search
      • create
      • delete
      • complete
      • newToken
      • clone
      • disable
    • accessedIamId (string): The IAM ID for the user being accessed.
    • accessedUserId (string): The user being accessed.
    • groupAccessType (string): Denotes how the specified group was accessed. Acceptable values are
      • update
      • get
      • search
      • create
      • delete
      • addUser
      • removeUser
    • groupIamId (string): The IAM ID for the group being accessed.
    • accessedGroupId (integer): The group being accessed.
    • keyAction (string): The action taken on the API key. Acceptable values are
      • get
      • delete
    • keyId (integer): The API key ID.
    • keyIamId (string): The IAM ID for the user who owns the API key accessed.
    • keyUserId (string): The user who owns the API key accessed.
  • extra (object): A JSON object representing the additional information to be logged/audited.

Response

The endpoint returns an object with a success array and failure array.

Example Requests

SQL Query: Data Source is Known:

{
"component": "featureStore",
"recordType": "externalQuery"
"profileId": 1,
"dataSourceId": 1,
"dataAccess": {
    "accessType": "query",
    "query": "SELECT * FROM my_data_source",
    "dataSourceTableName": "my_data_source"
},
"success": true
}

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/audit/createRecord

SQL Query: Data Source and Project are Known:

{
"component": "featureStore",
"recordType": "externalQuery"
"profileId": 1,
"projectId": 1,
"dataSourceId": 1,
"dataAccess": {
    "accessType": "query",
    "query": "SELECT * FROM my_data_source",
    "dataSourceTableName": "my_data_source"
},
"success": true
}

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/audit/createRecord

Failed SQL Query: Data Source and Project are Known:

{
"component": "featureStore",
"recordType": "externalQuery"
"profileId": 1,
"projectId": 1,
"purposeIds": [1],
"dataSourceId": 1,
"dataAccess": {
    "accessType": "query",
    "query": "SELECT * FROM my_data_source",
    "dataSourceTableName": "my_data_source"
},
"success": false,
"failureReason": "insufficientPermissions",
"recordType": "sqlQuery"
}

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/audit/createRecord