Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions api/controllers/audit/datatable.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
/**
* POST /api/v1/audit/datatable
*
* The rows of the Audit Log page (GET /audit), as DataTables server-side rows
* {draw, recordsTotal, recordsFiltered, data}. Needs audit.view.
*
* The page size is bounded in the query, as 1.6 AuditManagement.php does: the
* trail grows for the life of the install, so no request reads it whole. A
* `length` that is missing, -1, not a number, or above MAX_ROWS reads MAX_ROWS
* rows.
*
* Search: a case-insensitive substring match on createdBy, type, permission,
* outcome, subjectType, subjectLabel and ip. It runs in the database query.
* Without makeLikeModifierCaseInsensitive, sails-mongo matches case-sensitively.
*
* Order: createdAt DESC, then id DESC as a tie-break, so paging never skips or
* repeats rows that share a millisecond. The client sets ordering: false.
*/
const MAX_ROWS = 500;
const SEARCH_FIELDS = ['createdBy', 'type', 'permission', 'outcome', 'subjectType', 'subjectLabel', 'ip'];
const ROW_FIELDS = [
'id', 'createdAt', 'createdBy', 'ip', 'authSource', 'type', 'subjectType', 'subjectId',
'subjectLabel', 'permission', 'outcome', 'correlationId', 'affectedCount', 'text'
];

module.exports = {
friendlyName: 'Audit log datatable',
description: 'The audit trail, as DataTables server-side rows.',
fn: async function () {
const req = this.req;
const res = this.res;
if (!sails.helpers.audit.can(req, 'audit.view')) {
return res.forbidden();
}
// Safe for any JSON value (api/helpers/datatables/parse-request.js).
const parsed = sails.helpers.datatables.parseRequest.with({body: req.body});
const start = parsed.start;
const text = parsed.search;
// A length that is missing, -1, not a number, or above MAX_ROWS reads MAX_ROWS.
const length = parsed.length > 0 && parsed.length <= MAX_ROWS ? parsed.length : MAX_ROWS;

const where = text === '' ? {} : {or: SEARCH_FIELDS.map((field) => ({[field]: {contains: text}}))};
const recordsTotal = await sails.models.auditlog.count();
const recordsFiltered = text === '' ? recordsTotal : await sails.models.auditlog.count(where).meta({makeLikeModifierCaseInsensitive: true});
const rows = await sails.models.auditlog.find(where)
.meta({makeLikeModifierCaseInsensitive: true})
.sort([{createdAt: 'DESC'}, {id: 'DESC'}])
.skip(start)
.limit(length);
return res.json({
draw: parsed.draw,
recordsTotal,
recordsFiltered,
data: rows.map((row) => _.pick(row, ROW_FIELDS))
});
}
};
11 changes: 6 additions & 5 deletions api/controllers/host/pending-datatable.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ module.exports = {
if (!sails.helpers.audit.can(req, 'host.read')) {
return res.forbidden();
}
const body = req.body || {};
const start = Math.max(0, parseInt(body.start, 10) || 0);
const length = parseInt(body.length, 10);
const text = String(_.get(body, 'search.value', '')).trim().toLowerCase();
// Safe for any JSON value (api/helpers/datatables/parse-request.js).
const parsed = sails.helpers.datatables.parseRequest.with({body: req.body});
const start = parsed.start;
const length = parsed.length;
const text = parsed.search.toLowerCase();
const macText = text.replace(/[:\-. ]/g, '');

const pending = await sails.models.host.find({pending: true}).sort('name ASC');
Expand All @@ -41,7 +42,7 @@ module.exports = {
return /^[0-9a-f]{12}$/i.test(first) ? first.toLowerCase().match(/../g).join(':') : first;
};
return res.json({
draw: parseInt(body.draw, 10) || 0,
draw: parsed.draw,
recordsTotal: pending.length,
recordsFiltered: found.length,
data: page.map((host) => ({id: host.id, name: host.name, mac: show(host), description: host.description || ''}))
Expand Down
54 changes: 54 additions & 0 deletions api/controllers/pages/list/audit.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
const path = require('path');
const partialPath = path.join(__dirname,'..','..','..','..','views','pages','partials','list');
// GET /audit: the audit trail, read only (1.6 AuditManagement, issue #200). The
// rows come from POST /api/v1/audit/datatable. Needs audit.view.
//
// It does not call sails.helpers.listLocals: that helper needs a page-title
// entry, and the audit trail is not a CRUD model. So this action sets the
// locals that views/pages/list.ejs and the content header read. It sets no
// editBase, so no row links to an edit page.
module.exports = {
friendlyName: 'Audit log',
description: 'Audit Log page.',
inputs: {
},
exits: {
error: {
responseType: 'serverError'
},
forbidden: {
responseType: 'forbidden'
},
success: {
viewTemplatePath: 'pages/list',
description: 'Successful'
}
},
fn: async function () {
if (!sails.helpers.audit.can(this.req, 'audit.view')) {
throw 'forbidden';
}
return {
// The columns of 1.6 AuditManagement.php:103-120, in order.
theads: [
'When',
'Who',
'Action',
'Permission',
'Outcome',
'Subject',
'From'
],
section: 'Audit Log',
page: 'Audit Log',
singular: 'entry',
plural: 'entries',
model: 'audit',
// No row selection and no Delete selected, as 1.6 ($selectable = false).
selectable: false,
deleteButton: false,
partialname: path.join(partialPath, 'audit.js'),
...await sails.helpers.tableSettings()
};
}
};
55 changes: 55 additions & 0 deletions api/helpers/datatables/parse-request.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
/**
* The DataTables server-side request fields that a datatable action reads, made
* safe for a JSON body. A JSON body can hold any value, so String() or
* parseInt() on a field can throw (an object with a `toString` key), and a
* start that is not a safe integer makes Waterline refuse the skip.
*
* Input: body, the request body (may be undefined).
* Output: {draw, start, length, search}
* draw, start a whole number of at least 0 from a string or a number, and
* a safe integer. Anything else is 0.
* length the whole number, or NaN when the field is not a string or a
* number, or is not a safe integer. Each caller keeps its own
* rule for -1, 0 and NaN.
* search body.search.value as trimmed text, when it is a string or a
* finite number. Anything else is ''.
*
* Usage: const {draw, start, length, search} = sails.helpers.datatables.parseRequest.with({body: req.body});
* It returns the object itself, with no .now(): see api/helpers/permissions/resolve.js.
*/
// A whole number from a string or a number, or NaN.
function whole(value) {
let n = NaN;
if (typeof value === 'number') { n = Math.trunc(value); }
if (typeof value === 'string') { n = parseInt(value, 10); }
return Number.isSafeInteger(n) ? n : NaN;
}

module.exports = {
friendlyName: 'Parse a DataTables request',
description: 'The draw, start, length and search of a server-side request body, safe for any JSON value.',
sync: true,
inputs: {
body: {type: 'ref', description: 'The request body.'}
},
exits: {
success: {outputType: 'ref', description: '{draw, start, length, search}'}
},
// A sync machine must answer through exits.success.
fn: function ({body}, exits) {
// An array body has its own `length`, so it counts as no body.
const source = body !== null && typeof body === 'object' && !Array.isArray(body) ? body : {};
const nonNegative = (value) => {
const n = whole(value);
return n >= 0 ? n : 0;
};
const found = _.get(source, 'search.value');
const usable = typeof found === 'string' || (typeof found === 'number' && Number.isFinite(found));
return exits.success({
draw: nonNegative(source.draw),
start: nonNegative(source.start),
length: whole(source.length),
search: usable ? String(found).trim() : ''
});
}
};
3 changes: 3 additions & 0 deletions api/hooks/audit/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ const READ_ACTIONS = [
'task-history',
// The pending hosts DataTable (a POST read, like general/datatable).
'host/pending-datatable',
// The Audit Log DataTable. Without it, every page load and scroll of the
// audit page would write an AuditLog row.
'audit/datatable',
// Signs a JWT for the user and changes no record.
'auth/token'
];
Expand Down
8 changes: 8 additions & 0 deletions config/globals.js
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,14 @@ module.exports.globals = {
subLinks: [
{link: '/pxemenus/create', text: 'Create New iPXE Menu'}
]
},
// The 1.6 "Logging" group (FOGPage.php:899-902). It sits after the planned
// FOG Configuration entry (150).
{
order: 170, text: 'Logging', icon: 'fas fa-scroll',
children: [
{text: 'Audit Log', link: '/audit', icon: 'fas fa-clipboard-list'}
]
}
],
authenticationMechanisms: [
Expand Down
6 changes: 6 additions & 0 deletions config/permissions.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
module.exports.permissions = {
stock: {
// The Audit Log page (GET /audit, POST /api/v1/audit/datatable). The key is
// audit, not auditlog: a stock.auditlog entry would open the generic
// /api/v1/:model routes on the AuditLog model (ADR 0003).
audit: {
view: false
},
host: {
create: false,
destroy: false,
Expand Down
3 changes: 3 additions & 0 deletions config/policies.js
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ module.exports.policies = {
'host/pending-approve': ['isLoggedIn','isAuthenticated','apiCsrfGuard'],
'host/pending-delete': ['isLoggedIn','isAuthenticated','apiCsrfGuard'],

// The Audit Log rows (the action checks audit.view itself). It only reads.
'audit/datatable': ['isLoggedIn','isAuthenticated'],

// fog-agent enrollment admin routes (each action checks its host permission
// itself). apiCsrfGuard: a cookie-authed mutation on CSRF-exempt /api/v1.
'agent/enrollments': ['isLoggedIn','isAuthenticated','apiCsrfGuard'],
Expand Down
7 changes: 7 additions & 0 deletions config/routes.js
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ module.exports.routes = {
'POST /api/v1/host/pending/approve': {action: 'host/pending-approve', csrf: false},
'DELETE /api/v1/host/pending': {action: 'host/pending-delete', csrf: false},

// The Audit Log page rows (GET /audit). A POST read that needs audit.view; it
// must precede POST /api/v1/:model/datatable, or it is read as :model=audit.
'POST /api/v1/audit/datatable': {action: 'audit/datatable', csrf: false},

// fog-agent enrollment admin API (host permissions; must precede the :model
// routes, or GET /api/v1/agent/tokens is read as :model=agent/:id=tokens).
'GET /api/v1/agent/enrollments': {action: 'agent/enrollments', csrf: false},
Expand Down Expand Up @@ -128,6 +132,9 @@ module.exports.routes = {
'GET /hosts/pendingAgents': {action: 'pages/list/pending-agents'},
'GET /hosts/agentTokens': {action: 'pages/list/agent-tokens'},

// The Audit Log page (1.6 AuditManagement), read-only; it needs audit.view.
'GET /audit': {action: 'pages/list/audit'},

// Group Views
'GET /groups': {action: 'pages/list/groups'},
'GET /groups/create': {action: 'pages/create/groups'},
Expand Down
6 changes: 5 additions & 1 deletion docs/adr/0003-audit-trail.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,10 @@ The events:
A failed sign-in stores the attempted name and no reason, to avoid user
enumeration (1.6 stores none either).

- `audit.view` is the key `stock.audit.view`, not `auditlog`, so the generic
`:model` routes stay closed. It gates the Audit Log page (`GET /audit`) and
`POST /api/v1/audit/datatable`, which reads at most 500 rows per request.

## Differences from 1.6

- The correlation id is set per request. A middleware in `config/http.js` puts
Expand Down Expand Up @@ -90,7 +94,7 @@ enumeration (1.6 stores none either).

- Change rows with redaction (1.6 decisions 5 to 7): `AuditChange`, the
before and after values, and the redaction of a credential field.
- The `audit.view` and `audit.manage` permissions, and the Audit Log page.
- The `audit.manage` permission, with retention.
- Retention, and the rule that shrinking the trail writes a row first (1.6
decision 10).
- The machine paths other than the agent enrollment and renew routes.
Expand Down
60 changes: 60 additions & 0 deletions test/helpers/datatables-parse-request.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
const assert = require('assert');

// The datatables/parse-request helper: the draw, start, length and search of a
// server-side request, safe for any JSON value. A JSON body can make String()
// or parseInt() throw (an object with a toString key), and a start of 1e20 is
// not a safe integer, so Waterline refuses it as a skip.
describe('datatables parse-request helper::', () => {
const parse = (body) => sails.helpers.datatables.parseRequest.with({body});
const OBJ = {toString: 1};

it('reads draw, start, length and search from a form-style body', () => {
assert.deepStrictEqual(parse({draw: '3', start: '20', length: '10', search: {value: ' Lab '}}),
{draw: 3, start: 20, length: 10, search: 'Lab'});
assert.deepStrictEqual(parse({draw: 3, start: 20, length: -1, search: {value: 7}}),
{draw: 3, start: 20, length: -1, search: '7'});
});

it('turns a missing or unusable body into the defaults', () => {
[undefined, null, 'text', 5, []].forEach((body) => {
const got = parse(body);
assert.deepStrictEqual([got.draw, got.start, got.search], [0, 0, ''], JSON.stringify(body));
assert.ok(Number.isNaN(got.length), JSON.stringify(body));
});
});

// [value, expected] for draw and start.
const WHOLE = [
['5', 5], [5, 5], [5.9, 5], ['5abc', 5], [0, 0], ['0', 0], [-1, 0], ['-3', 0], ['x', 0], ['', 0],
['99999999999999999999', 0], [1e20, 0], [Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER],
[NaN, 0], [Infinity, 0], [null, 0], [true, 0], [OBJ, 0], [[5], 0], [undefined, 0]
];
['draw', 'start'].forEach((field) => {
it(`reads ${field} as a safe integer of at least 0, else 0`, () => {
WHOLE.forEach(([value, want]) => {
assert.strictEqual(parse({[field]: value})[field], want, `${field} ${String(typeof value === 'object' ? JSON.stringify(value) : value)}`);
});
});
});

it('reads length as a safe integer, else NaN, and keeps -1 and 0', () => {
[['10', 10], [10, 10], [-1, -1], ['-1', -1], [0, 0], [1000, 1000]].forEach(([value, want]) => {
assert.strictEqual(parse({length: value}).length, want, String(value));
});
['x', '', '99999999999999999999', 1e20, NaN, Infinity, null, true, OBJ, [5], undefined].forEach((value) => {
assert.ok(Number.isNaN(parse({length: value}).length), typeof value === 'object' ? JSON.stringify(value) : String(value));
});
});

it('reads search only from a string or a finite number, else an empty string', () => {
[['lab', 'lab'], [' lab ', 'lab'], [12, '12'], [0, '0'], ['', '']].forEach(([value, want]) => {
assert.strictEqual(parse({search: {value}}).search, want, String(value));
});
[OBJ, {x: 1}, [1], null, true, NaN, Infinity, undefined].forEach((value) => {
assert.strictEqual(parse({search: {value}}).search, '', typeof value === 'object' ? JSON.stringify(value) : String(value));
});
assert.strictEqual(parse({search: 'lab'}).search, '');
assert.strictEqual(parse({search: null}).search, '');
assert.strictEqual(parse({search: OBJ}).search, '');
});
});
3 changes: 2 additions & 1 deletion test/helpers/menu.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,8 @@ describe('Sidebar menu helpers::', () => {
['Tasks', 'fas fa-bars-progress'],
['Workflows', 'fas fa-diagram-project'],
['User Administration', 'fas fa-shield'],
['iPXE Menu', 'fas fa-list-ol']
['iPXE Menu', 'fas fa-list-ol'],
['Logging', 'fas fa-scroll']
]);
assert.deepStrictEqual(menu.filter((n) => n.pluginOption), []);
const admin = menu.find((n) => n.text === 'User Administration');
Expand Down
9 changes: 9 additions & 0 deletions test/helpers/permissions-resolve.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,15 @@ describe('Permissions resolve helper::', () => {
assert.ok(leaves(result).every(([, value]) => value === false));
});

// stock.audit.view opens the Audit Log page (issue #200). The key is audit,
// not auditlog, so the generic /api/v1/:model routes still refuse the model.
it('resolves stock.audit.view true for an admin role and false for a role with no grant', () => {
assert.strictEqual(resolve([{isAdmin: true, permissions: {}}]).stock.audit.view, true);
assert.strictEqual(resolve([B]).stock.audit.view, false);
assert.strictEqual(resolve([{permissions: {stock: {audit: {view: true}}}}]).stock.audit.view, true);
assert.strictEqual(sails.config.permissions.stock.audit.view, false);
});

it('returns a new tree, so a change to it leaves the defaults alone', () => {
const result = resolve([]);
assert.notStrictEqual(result.stock, sails.config.permissions.stock);
Expand Down
Loading
Loading