Skip to content

Commit

Permalink
Finish vocab
Browse files Browse the repository at this point in the history
  • Loading branch information
quinnturner committed Dec 1, 2023
1 parent 52dac04 commit 951b891
Show file tree
Hide file tree
Showing 30 changed files with 1,511 additions and 44 deletions.
24 changes: 14 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# owasp-logging
# OWASP

This package implements the OWASP Cheat Sheet for [Application Logging Vocabulary](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#input-validation-input), a standard vocabulary for logging security events.
This package is intended to assist developers to follow OWASP best practices.

Currently, it implements the OWASP Cheat Sheet for [Application Logging Vocabulary](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#input-validation-input), a standard vocabulary for logging security events.

The intent is to simplify monitoring and alerting such that, assuming developers trap errors and log them using this vocabulary, monitoring and alerting would be improved by simply keying on these terms.

Expand All @@ -9,14 +11,16 @@ This logging standard would seek to define specific keywords which, when applied
## Installation

```bash
npm install owasp-logging
# yarn add owasp-logging
# pnpm install owasp-logging
# bun install owasp-logging
npm install owasp
# yarn add owasp
# pnpm install owasp
# bun install owasp
```

## Usage

### Logging vocabulary

Here is an example of how to use this package with [pino](https://github.com/pinojs/pino)
and [Express](https://github.com/expressjs/express) to log authentication events.

Expand All @@ -27,9 +31,9 @@ and [Express](https://github.com/expressjs/express) to log authentication events

```ts
import { Router } from 'express';
import { authn_login_fail, authn_login_fail_max, authn_login_success } from 'owasp-logging';
import { authn_login_fail, authn_login_fail_max, authn_login_success } from 'owasp/vocab';
// Or, if you want to simplify imports, you can do:
// import * as owasp from 'owasp-logging';
// import * as owasp from 'owasp-helpers';
import { logger as rootLogger } from '../logger.js';

const router = Router();
Expand All @@ -48,7 +52,7 @@ router.route("/login").post(async (req, res, next) => {
if (!userId || !password || userId.length === 0 || password.length === 0) {
logger.warn(
{
// owasp-logging provides a set of standard events to log.
// owasp-helpers provides a set of standard events to log.
// Use the `event` property to log the event.
event: authn_login_fail(userId), // The result of this function is: `authn_login_fail:${userId}`
},
Expand Down Expand Up @@ -152,5 +156,5 @@ Ensure linting, formatting, and tests pass before submitting a PR.

```bash
bun run check
bun test
bun test # let's keep the test coverage at 100%!
```
Binary file modified bun.lockb
Binary file not shown.
18 changes: 9 additions & 9 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"name": "owasp-logging",
"name": "owasp",
"version": "1.0.0",
"type": "module",
"license": "MIT",
Expand All @@ -9,24 +9,24 @@
"author": {
"name": "Quinn Turner"
},
"homepage": "https://github.com/quinnturner/owasp-logging#readme",
"homepage": "https://github.com/quinnturner/owasp#readme",
"bugs": {
"url": "https://github.com/quinnturner/owasp-logging/issues"
"url": "https://github.com/quinnturner/owasp/issues"
},
"keywords": [
"owasp",
"logging",
"security"
],
"exports": {
".": {
"./vocab": {
"import": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
"types": "./dist/vocab.d.ts",
"default": "./dist/vocab.js"
},
"require": {
"types": "./dist/index.d.cts",
"default": "./dist/index.cjs"
"types": "./dist/vocab.d.cts",
"default": "./dist/vocab.cjs"
}
},
"./package.json": "./package.json"
Expand All @@ -43,7 +43,7 @@
"build": "tsup --config tsup.config.ts"
},
"devDependencies": {
"@biomejs/biome": "^1.4.0",
"@biomejs/biome": "^1.4.1",
"bun-types": "^1.0.14",
"tsup": "^8.0.1",
"type-fest": "^4.8.2",
Expand Down
5 changes: 1 addition & 4 deletions src/index.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1 @@
export * from "./authentication.js";
export * from "./authorization.js";
export * from "./excessive-use.js";
export * from "./file-upload.js";
export * from "./vocab/index.js";
File renamed without changes.
24 changes: 12 additions & 12 deletions src/authentication.ts → src/vocab/authentication.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import type { Join } from "type-fest";
* "requestId": "4c682970-ef75-4605-93f2-ab7cf5316d83"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_successuserid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_login_success](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_successuserid)
*/
export function authn_login_success<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -51,7 +51,7 @@ export function authn_login_success<U extends string | number | bigint>(
* "requestId": "b2b0fc16-cfc1-42cc-a1a7-102a11e7fa6e"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_successafterfailuseridretries
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_login_successafterfail](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_successafterfailuseridretries)
*/
export function authn_login_successafterfail<
U extends string,
Expand Down Expand Up @@ -82,7 +82,7 @@ export function authn_login_successafterfail<
* "requestId": "b7c29e30-199e-4234-a8f1-fff0c12f1624"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_failuserid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_login_fail](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_failuserid)
*/
export function authn_login_fail<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -112,7 +112,7 @@ export function authn_login_fail<U extends string | number | bigint>(
* "requestId": "b7c29e30-199e-4234-a8f1-fff0c12f1624"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_fail_maxuseridmaxlimitint
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_login_fail_max](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_fail_maxuseridmaxlimitint)
*/
export function authn_login_fail_max<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -159,7 +159,7 @@ export function authn_login_fail_max<
* "requestId": "e6a7c70a-7972-49c9-a056-1af31cecf334"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_lockuseridreason
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_login_lock](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_login_lockuseridreason)
*/
export function authn_login_lock<
U extends string | number | bigint,
Expand Down Expand Up @@ -198,7 +198,7 @@ export function authn_login_lock<
* "requestId": "72b29ffe-4b2a-4eef-9b4b-e9dc36483d28"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_password_changeuserid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_password_change](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_password_changeuserid)
*/
export function authn_password_change<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -227,7 +227,7 @@ export function authn_password_change<U extends string | number | bigint>(
* "requestId": "e5c80286-e7b4-4add-ab67-24ce28c7f187"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_password_change_failuserid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_password_change_fail](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_password_change_failuserid)
*/
export function authn_password_change_fail<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -258,7 +258,7 @@ export function authn_password_change_fail<U extends string | number | bigint>(
* "requestId": "c1a514a9-70f1-4496-8c69-ebf9337783f6"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_impossible_traveluseridregion1region2
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_impossible_travel](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_impossible_traveluseridregion1region2)
*/
export function authn_impossible_travel<
U extends string | number | bigint,
Expand Down Expand Up @@ -290,7 +290,7 @@ export function authn_impossible_travel<
* "requestId": "e6002b7c-87f4-45c9-abf6-f1e0f94523d5"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_createduserid-entitlements
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_token_created](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_createduserid-entitlements)
*/
export function authn_token_created<
U extends string | number | bigint,
Expand Down Expand Up @@ -323,7 +323,7 @@ export function authn_token_created<
* "requestId": "caa98ad0-4b9c-4b20-8633-6be104b1933b"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_revokeduseridtokenid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_token_revoked](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_revokeduseridtokenid)
*/
export function authn_token_revoked<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -363,7 +363,7 @@ export function authn_token_revoked<
* "requestId": "1cfdc054-b87a-4533-9c9a-d329bca0da44"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_reuseuseridtokenid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_token_reuse](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_reuseuseridtokenid)
*/
export function authn_token_reuse<U extends string | number | bigint>(
userId: U,
Expand Down Expand Up @@ -402,7 +402,7 @@ export function authn_token_reuse<
* "requestId": "ecd6341b-bc7c-4301-9c75-f49427f59406"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_deleteappid
* @see [OWASP Logging Vocabulary Cheat Sheet - authn_token_delete](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authn_token_deleteappid)
*/
export function authn_token_delete<A extends string | number | bigint>(
appId: A,
Expand Down
File renamed without changes.
6 changes: 3 additions & 3 deletions src/authorization.ts → src/vocab/authorization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
* "requestId": "00b13b12-51ab-49bc-94be-34c450804850"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authz_failuseridresource
* @see [OWASP Logging Vocabulary Cheat Sheet - authz_fail](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authz_failuseridresource)
*/
export function authz_fail<
U extends string | number | bigint,
Expand Down Expand Up @@ -52,7 +52,7 @@ export function authz_fail<
* "requestId": "5e952d3b-97b6-4c20-a241-b3aa9a591647"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authz_changeuseridfromto
* @see [OWASP Logging Vocabulary Cheat Sheet - authz_change](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authz_changeuseridfromto)
*/
export function authz_change<
U extends string | number | bigint,
Expand Down Expand Up @@ -87,7 +87,7 @@ export function authz_change<
* "requestId": "e02ffa1d-99b6-4616-b54e-5f51ed208331"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authz_changeuseridfromto
* @see [OWASP Logging Vocabulary Cheat Sheet - authz_admin](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#authz_changeuseridfromto)
*/
export function authz_admin<
U extends string | number | bigint,
Expand Down
File renamed without changes.
2 changes: 1 addition & 1 deletion src/excessive-use.ts → src/vocab/excessive-use.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
* "requestId": "e997c333-fd0a-4880-b6d0-27e871285e50"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#excess_rate_limit_exceededuseridmax
* @see [OWASP Logging Vocabulary Cheat Sheet - excess_rate_limit_exceeded](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#excess_rate_limit_exceededuseridmax)
*/
export function excess_rate_limit_exceeded<
U extends string | number | bigint,
Expand Down
File renamed without changes.
8 changes: 4 additions & 4 deletions src/file-upload.ts → src/vocab/file-upload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
* "requestId": "6e48278f-5f2c-4af0-b821-9d83f1cce30b"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_completeuseridfilenametype
* @see [OWASP Logging Vocabulary Cheat Sheet - upload_complete](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_completeuseridfilenametype)
*/
export function upload_complete<
U extends string | number | bigint,
Expand Down Expand Up @@ -64,7 +64,7 @@ export function upload_complete<
* "requestId": "7d1fbc36-fc8b-4dc3-8e79-841216f48ada"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_storedfilenamefromto
* @see [OWASP Logging Vocabulary Cheat Sheet - upload_stored](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_storedfilenamefromto)
*/
export function upload_stored<N extends string, T extends string>(
filename: N,
Expand Down Expand Up @@ -105,7 +105,7 @@ export function upload_stored<N extends string, T extends string>(
* "requestId": "46f449eb-bd37-43ef-a5a6-8d76d80b8975"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_validationfilenamevirusscanimagemagickfailedincompletepassed
* @see [OWASP Logging Vocabulary Cheat Sheet - upload_validation](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_validationfilenamevirusscanimagemagickfailedincompletepassed)
*/
export function upload_validation<
N extends string,
Expand Down Expand Up @@ -137,7 +137,7 @@ export function upload_validation<
* "requestId": "d4fc4479-210b-4d89-ae1e-4fe7b595cbb4"
* }
* ```
* @see https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_deleteuseridfileid
* @see [OWASP Logging Vocabulary Cheat Sheet - upload_delete](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#upload_deleteuseridfileid)
*/
export function upload_delete<
U extends string | number | bigint,
Expand Down
12 changes: 12 additions & 0 deletions src/vocab/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
export * from "./authentication.js";
export * from "./authorization.js";
export * from "./excessive-use.js";
export * from "./file-upload.js";
export * from "./input-validation.js";
export * from "./malicious-behavior.js";
export * from "./privilege-changes.js";
export * from "./sensitive-data-changes.js";
export * from "./sequence-errors.js";
export * from "./session-management.js";
export * from "./system-events.js";
export * from "./user-management.js";
9 changes: 9 additions & 0 deletions src/vocab/input-validation.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import { describe, expect, it } from "bun:test";
import { input_validation_fail } from "./input-validation";

describe("input_validation_fail", () => {
it("should return the correct string", () => {
const result = input_validation_fail("field1", "user123");
expect(result).toBe("input_validation_fail:field1,user123");
});
});
33 changes: 33 additions & 0 deletions src/vocab/input-validation.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
/**
* When input validation fails on the server-side it must either be because
* a) sufficient validation was not provided on the client, or
* b) client-side validation was bypassed.
* In either case it's an opportunity for attack and should be mitigated quickly.
*
* **Level:** `WARN`
*
* @example
* ```ts
* const field = 'date_of_birth';
* const userId = "joebob1";
* logger.warn({ event: input_validation_fail(field, userId) }, `User ${userId} submitted data that failed validation.`);
* ```
* @example
* ```json
* {
* "datetime": "2019-01-01 00:00:00,000",
* "appid": "foobar.netportal_auth",
* "event": "input_validation_fail:date_of_birth,joebob1",
* "level": "WARN",
* "description": "User joebob1 submitted data that failed validation.",
* "requestId": "e22569d2-5fb6-4453-ae7e-c496a2584d94"
* }
* ```
* @see [OWASP Logging Vocabulary Cheat Sheet - input_validation_fail](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html#input-validation-input)
*/
export function input_validation_fail<
F extends string,
U extends string | number | bigint,
>(field: F, userId: U) {
return `input_validation_fail:${field},${userId}` as const;
}
Loading

0 comments on commit 951b891

Please sign in to comment.