Retraced Audit Log

<a href="https://www.npmjs.com/package/@retracedhq/retraced"><img src="https://img.shields.io/npm/dt/@retracedhq/retraced" alt="npm" ></a>
<a href="https://hub.docker.com/r/retracedhq/retraced"><img src="https://img.shields.io/docker/pulls/retracedhq/retraced" alt="Docker pulls"></a>
<a href="https://github.com/retracedhq/retraced/stargazers"><img src="https://img.shields.io/github/stars/retracedhq/retraced" alt="Github stargazers"></a>
<a href="https://github.com/retracedhq/retraced/issues"><img src="https://img.shields.io/github/issues/retracedhq/retraced" alt="Github issues"></a>
<a href="https://github.com/retracedhq/retraced/blob/main/LICENSE"><img src="https://img.shields.io/github/license/retracedhq/retraced" alt="license"></a>
<a href="https://twitter.com/boxyhq"><img src="https://img.shields.io/twitter/follow/boxyhq?style=social" alt="Twitter"></a>
<a href="https://discord.gg/uyb7pYt4Pa"><img src="https://img.shields.io/discord/877585485235630130" alt="Discord"></a>

Retraced is the easiest way to integrate a compliant audit log into your application. It provides a searchable, exportable record of read/write events. Client libraries are available for Go and Javascript.

Documentation

Please head to https://boxyhq.com/docs/retraced/overview for detailed documentation on how to get started with Retraced.

• Step by step tutorial video

Usage

Running with docker-compose

docker-compose up -d or npm run dev

Note: ADMIN_ROOT_TOKEN has been set to dev so you can test the setup locally. Please remember to change this (and other relevant sensitive env vars/secrets) in production.

Run an example to see how Retraced works

Git checkout the Logs Viewer repo and run npm i followed by npm run dev to start an example which uses Retraced to show you some auto generated events. Refresh the UI a few times for the auto-generated audit logs to kick in. You can also ingest a few custom logs using the following curl command:-

curl -X POST -H "Content-Type: application/json" -H "Authorization: token=dev" -d '{
  "action": "some.record.created",
  "teamId": "boxyhq",
  "group": {
    "id": "dev",
    "name": "dev"
  },
  "crud": "c",
  "created": "2023-01-16T15:48:44.573Z",
  "source_ip": "127.0.0.1",
  "actor": {
    "id": "jackson@boxyhq.com",
    "name": "Jackson"
  },
  "target": {
    "id": "100",
    "name": "tasks",
    "type": "Tasks"
  }
}' http://localhost:3000/auditlog/publisher/v1/project/dev/event

You can also use the Admin Portal but will need to setup the SMTP env vars so that you can use the magic link to log into the Portal, we are working to support other forms of authentication and would love to hear which provider you'd like supported next.

Running with Skaffold

You could alternatively use Skaffold instead of docker-compose to run Retraced locally.

npm run run:skaffold or skaffold run -f skaffold-dev.yaml --status-check=false --force=true

Swagger Documentation

Swagger spec is generated from source using TSOA

By default, a swagger spec is built as part of npm run build, and is served by express at /publisher/v1/swagger.json.

Generating a spec

To generate swagger.json from Typescript sources use

npm run swagger

The outputs will be written to build/swagger.json

Contributing

Thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are appreciated.

Please try to create bug reports that are:

• Reproducible. Include steps to reproduce the problem.
• Specific. Include as much detail as possible: which version, what environment, etc.
• Unique. Do not duplicate existing opened issues.
• Scoped to a Single Bug. One bug per report.

Support

Reach out to the maintainers at one of the following places:

• GitHub Issues (Bug reports, Contributions)

Community

• Discord (For live discussion with the Community and BoxyHQ team)
• Twitter (Get the news fast)