@pangeacyber/react-mui-audit-log-viewer v0.0.74

Motivation

The Audit Log Viewer can be used to search, view, and verify tamperproofing of all logs stored by the Secure Audit Log service. It allows users to perform searches, navigate through pages of results, and interact with the audit log data.

An application using the Pangea Audit Service may also require that the audit logs are presented in the end application, because of this we made the log viewer React component that Pangea uses within it's Console available as an NPM package, such that it could be embed directly into an app.

The AuditLogViewer component is a React component built using the Material-UI (MUI) component library. MUI was used because it is the same component used within the Pangea Console.

Getting Started

Install Material-UI library and the AuditLogViewer NPM package.

npm

npm install @mui/material @emotion/react @emotion/styled @pangeacyber/react-mui-audit-log-viewer

yarn

yarn add @mui/material @emotion/react @emotion/styled @pangeacyber/react-mui-audit-log-viewer

Peer dependencies

Please note that react and react-dom are peer dependencies too:

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0",
  "react-dom": "^17.0.0 || ^18.0.0"
},

To learn more about Material-UI (MUI) check out their official documentation(https://mui.com/material-ui/getting-started/installation/).

Props

The AuditLogViewer component accepts the following props:

• initialQuery (optional): A string representing the default initial search query.
• onSearch: A function that takes a body of type Audit.SearchRequest and returns a promise resolving to a Audit.SearchResponse. This function is called when the user performs a search. Should make a call to the Audit Service /search endpoint proxied through your application server.
• searchOnChange (optional): A optional boolean to prevent the search input to auto search on change. If false will only search when the "Search" button is clicked or if "Enter" is typed while focused on the search input. Default: true
• onPageChange: A function that takes a body of type Audit.ResultRequest and returns a promise resolving to a Audit.ResultResponse. This function is called when the user navigates to a different page of results. Should make a call to the Audit Service /results endpoint proxied through your application server.
• verificationOptions (optional): An object containing verification options. Letting you control whether or not to include client side verification check on audit logs.
  • onFetchRoot: A function that takes a body of type Audit.RootRequest and returns a promise resolving to a Audit.RootResponse. This function is called when the root data needs to be fetched. Should make a call to the Audit Service /root endpoint proxied through your application server.
  • ModalChildComponent (optional): A functional component that serves as a child component for the VerificationModal dialog.
  • onCopy (optional): A function that takes a message string and a value string. It is called when the user copies a value from the component from the VerificationModal component
• sx (optional): Additional CSS styles applied to the component using the SxProps interface.
• pageSize (optional): The number of items to display per page.
• dataGridProps (optional): Additional props to be passed to the underlying MUI DataGrid component.
• fields (optional): An object containing partial definitions for the grid columns. The keys of theon object correspond to properties of the Event type, and the values are partial definitions of the GridColDef type.
• visibilityModel (optional): An object containing partial definitions for the visibility of the grid columns. The keys of the object correspond to properties of the Event type, and the values are boolean values indicating the visibility of the column.
• filters (optional): An object representing the public audit query used to filter the audit log data.
• config (optional): An object representing the authentication configuration. Used to fetch your project custom Audit schema, so the AuditLogViewer component can dynamically update as you update your configuration in Pangea Console.
  • clientToken: string;
  • domain: string;
  • configId (conditionally-optional): A configId is conditionally optional depending on if your project in Pangea has multiple Audit configurations. With multiple Audit configurations the configId is required to identify which Audit schema should be fetched.
• schema (optional): An object representing the audit schema. With Audit Service custom schema support, you can change the expected Audit schema. This will control what fields are rendered.
• schemaOptions (optional): An object representing options for mutating the audit schema the component uses.
  • hiddenFields (optional): A list of field ids to hide/remove from the schema before it is rendered. Will completely hide the field from the table, visibility options, and filtering

For a deeper dive into the Prop interface check the source code here

Example

The following is brief example for how to initialize the AuditLogViewer component.

import React from "react";
import {
  Audit,
  AuditLogViewerProps,
  AuditLogViewer,
} from "@pangeacyber/react-mui-audit-log-viewer";

const MyComponent: React.FC = () => {
  const handleSearch = async (body: Audit.SearchRequest) => {
    // Perform search logic here
    const response = await api.searchAuditLogs(body);
    return response;
  };

  const handlePageChange = async (body: Audit.ResultRequest) => {
    // Handle page change logic here
    const response = await api.getAuditLogResults(body);
    return response;
  };

  return (
    <AuditLogViewer
      initialQuery="message:testing"
      onSearch={handleSearch}
      onPageChange={handlePageChange}
    />
  );
};

Customization

The AuditLogViewer component uses the Material-UI component library, so styling of the component can be controlled through a MUI Theme. See Theming documentation here

What to apply your Pangea branding to your end application? Check out the @pangeacyber/react-mui-branding NPM package here. The BrandingThemeProvider can fetch your Pangea Projects Branding and apply the styling to a Material-UI Theme.

API Reference

Audit Service API's(https://pangea.cloud/docs/api/audit)

Development

Pre-requisites

1. Node.js v16 (IMPORTANT!)
2. yarn 1.x

First, run the development server:

yarn install
yarn storybook

The VerificationAuditLogViewer storybook example does not use mock audit logs to render the AuditLogViewer instead it will read a .env file to hit your Audit Service Config.

Retrieve your audit service token, client token and domain from the Pangea Console Audit service dashboard and add the to a .env file. The environment file is git ignored.

STORYBOOK_PANGEA_TOKEN = "{SERVICE_TOKEN}"
STORYBOOK_CLIENT_TOKEN = "{CLIENT_TOKEN}"
STORYBOOK_SERVICE_DOMAIN = "{DOMAIN}"

Open http://localhost:6060 with your browser to view the component storybook