diff --git a/api/controllers/activity/datatable.js b/api/controllers/activity/datatable.js new file mode 100644 index 0000000..51d8476 --- /dev/null +++ b/api/controllers/activity/datatable.js @@ -0,0 +1,44 @@ +/** + * POST /api/v1/activity/datatable + * + * The rows of the Activity page (GET /activity), as DataTables server-side rows + * {draw, recordsTotal, recordsFiltered, data}. Needs activity.view. + * + * Activity is a view over the audit trail (1.6 ADR 0023). A row shows when the + * write succeeded and named its record (an access.api or access.page row with a + * subjectType), or when the event marks itself renderable (the agent events). + * Denials, failures, sign-ins and sign-outs stay on the Audit Log page only. + * + * The paging, the 500-row bound, the search and the order are in + * api/helpers/audit/datatable.js. Each row carries a server-built `summary` + * (api/helpers/audit/summary.js). + */ +const SEARCH_FIELDS = ['createdBy', 'subjectType', 'subjectLabel', 'ip']; +const ROW_FIELDS = ['id', 'createdAt', 'createdBy', 'ip', 'text']; +// The 1.6 "Administrative actions" rule, in Waterline. +const RULE = { + outcome: 'allowed', + or: [ + {renderable: true}, + {type: {in: ['access.api', 'access.page']}, subjectType: {'!=': ''}} + ] +}; + +module.exports = { + friendlyName: 'Activity datatable', + description: 'The Activity feed, as DataTables server-side rows.', + fn: async function () { + const req = this.req; + const res = this.res; + if (!sails.helpers.audit.can(req, 'activity.view')) { + return res.forbidden(); + } + return res.json(await sails.helpers.audit.datatable.with({ + req, + where: RULE, + searchFields: SEARCH_FIELDS, + fields: ROW_FIELDS, + extra: (row) => ({summary: sails.helpers.audit.summary.with({row})}) + })); + } +}; diff --git a/api/controllers/audit/datatable.js b/api/controllers/audit/datatable.js index 66d026e..68f41dc 100644 --- a/api/controllers/audit/datatable.js +++ b/api/controllers/audit/datatable.js @@ -2,21 +2,9 @@ * 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. + * {draw, recordsTotal, recordsFiltered, data}. Needs audit.view. The paging, the + * 500-row bound, the search and the order are in api/helpers/audit/datatable.js. */ -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', @@ -32,26 +20,6 @@ module.exports = { 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)) - }); + return res.json(await sails.helpers.audit.datatable.with({req, where: {}, searchFields: SEARCH_FIELDS, fields: ROW_FIELDS})); } }; diff --git a/api/controllers/pages/list/activity.js b/api/controllers/pages/list/activity.js new file mode 100644 index 0000000..c031522 --- /dev/null +++ b/api/controllers/pages/list/activity.js @@ -0,0 +1,51 @@ +const path = require('path'); +const partialPath = path.join(__dirname,'..','..','..','..','views','pages','partials','list'); +// GET /activity: what has been done on the server, in plain words, read only +// (1.6 ActivityManagement, issue #206). The rows come from +// POST /api/v1/activity/datatable. Needs activity.view. +// +// It does not call sails.helpers.listLocals, for the reason that +// pages/list/audit.js gives: the activity feed is a view over the audit trail, +// not a CRUD model. It sets no editBase, so no row links to an edit page. +module.exports = { + friendlyName: 'Activity', + description: 'Activity 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, 'activity.view')) { + throw 'forbidden'; + } + return { + // The columns of 1.6 ActivityManagement.php:199-204, in order. + theads: [ + 'Who', + 'When', + 'What', + 'From' + ], + section: 'Activity', + page: 'Activity', + singular: 'entry', + plural: 'entries', + model: 'activity', + // No row selection and no Delete selected, as 1.6 ($selectable = false). + selectable: false, + deleteButton: false, + partialname: path.join(partialPath, 'activity.js'), + ...await sails.helpers.tableSettings() + }; + } +}; diff --git a/api/helpers/audit/datatable.js b/api/helpers/audit/datatable.js new file mode 100644 index 0000000..cdd66fc --- /dev/null +++ b/api/helpers/audit/datatable.js @@ -0,0 +1,72 @@ +/** + * The DataTables server-side rows of an AuditLog view: the Audit Log page + * (audit/datatable.js) and the Activity page (activity/datatable.js). The caller + * checks its own permission first, then calls this helper. + * + * 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 the searchFields. It runs in the + * database query. Without makeLikeModifierCaseInsensitive, sails-mongo matches + * case-sensitively. With a search, the query is {and: [where, {or: search}]}; a + * `where` of {} is left out, so the query is {or: search}. + * + * recordsTotal counts the rows that match `where`, not the whole trail. + * + * 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. + * + * Inputs: req, where (the base filter; {} for none), searchFields (field names), + * fields (the row fields to pick), extra (optional: called with the stored row, + * returns more keys to add to the picked row, such as Activity's `summary`). + * + * Usage: await sails.helpers.audit.datatable.with({req, where, searchFields, fields}) + */ +const MAX_ROWS = 500; + +module.exports = { + friendlyName: 'Audit datatable', + description: 'AuditLog rows as DataTables server-side rows.', + inputs: { + req: {type: 'ref', required: true}, + // Typed, so a wrong shape fails at the call, not deep in the query. + where: {type: {}, required: true}, + searchFields: {type: ['string'], required: true}, + fields: {type: ['string'], required: true}, + extra: {type: 'ref', defaultsTo: null} + }, + exits: { + success: {description: '{draw, recordsTotal, recordsFiltered, data}.'} + }, + fn: async function ({req, where, searchFields, fields, extra}) { + // 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; + + // Waterline normalizes criteria in place, and one request runs up to three + // queries on `where`, so each query gets its own copy. + const queryOf = () => { + if (text === '') { return _.cloneDeep(where); } + const search = {or: searchFields.map((field) => ({[field]: {contains: text}}))}; + return Object.keys(where).length === 0 ? search : {and: [_.cloneDeep(where), search]}; + }; + const recordsTotal = await sails.models.auditlog.count(_.cloneDeep(where)); + const recordsFiltered = text === '' ? recordsTotal : await sails.models.auditlog.count(queryOf()).meta({makeLikeModifierCaseInsensitive: true}); + const rows = await sails.models.auditlog.find(queryOf()) + .meta({makeLikeModifierCaseInsensitive: true}) + .sort([{createdAt: 'DESC'}, {id: 'DESC'}]) + .skip(start) + .limit(length); + return { + draw: parsed.draw, + recordsTotal, + recordsFiltered, + data: rows.map((row) => Object.assign(_.pick(row, fields), extra ? extra(row) : {})) + }; + } +}; diff --git a/api/helpers/audit/summary.js b/api/helpers/audit/summary.js new file mode 100644 index 0000000..6836766 --- /dev/null +++ b/api/helpers/audit/summary.js @@ -0,0 +1,61 @@ +/** + * The plain-words summary of an AuditLog row, for the Activity page + * (GET /activity, issue #206; 1.6 ActivityManagement.php). + * + * It is built at read time from the stored fields, so a row written before + * this helper existed gets a summary too. + * + * - A renderable row: the event name, `, ` and the subject, then `: ` and the + * stored text. agent.enroll is "Agent enrollment", agent.token is "Agent + * token", any other type is shown as it is. + * - An access.* row: a verb from the HTTP method that starts `text`, then the + * subject, then ` (N records)` when more than one record changed. + * - Any other row: the stored text. + * + * The subject is the type, then the label in double quotes, else #id. + * + * Inputs: row (an AuditLog row, or any object with the same fields). + * + * Usage: sails.helpers.audit.summary.with({row}) + */ +const EVENTS = { + 'agent.enroll': 'Agent enrollment', + 'agent.token': 'Agent token' +}; +const VERBS = {DELETE: 'Deleted', PUT: 'Updated', PATCH: 'Updated', POST: 'Saved'}; + +module.exports = { + friendlyName: 'Summarize an audit row', + description: 'One plain sentence for an AuditLog row.', + sync: true, + inputs: { + row: {type: 'ref', required: true} + }, + exits: { + success: {description: 'The summary string.'} + }, + fn: function ({row}) { + let subject = ''; + if (row.subjectType) { + subject = row.subjectType; + if (row.subjectLabel) { + subject += ` "${row.subjectLabel}"`; + } else if (row.subjectId) { + subject += ` #${row.subjectId}`; + } + } + const text = row.text || ''; + if (row.renderable === true) { + const event = EVENTS[row.type] || row.type; + return `${event}${subject ? `, ${subject}` : ''}: ${text}`; + } + if (typeof row.type === 'string' && row.type.startsWith('access.')) { + const verb = VERBS[text.split(' ')[0]]; + if (verb) { + const count = row.affectedCount > 1 ? ` (${row.affectedCount} records)` : ''; + return `${verb}${subject ? ` ${subject}` : ''}${count}`; + } + } + return text; + } +}; diff --git a/api/hooks/audit/index.js b/api/hooks/audit/index.js index 57d6d44..9f9a6b2 100644 --- a/api/hooks/audit/index.js +++ b/api/hooks/audit/index.js @@ -42,6 +42,8 @@ const READ_ACTIONS = [ // The Audit Log DataTable. Without it, every page load and scroll of the // audit page would write an AuditLog row. 'audit/datatable', + // The Activity DataTable: the same reason as the Audit Log one. + 'activity/datatable', // Signs a JWT for the user and changes no record. 'auth/token' ]; diff --git a/config/globals.js b/config/globals.js index 20f2376..f1dbaae 100644 --- a/config/globals.js +++ b/config/globals.js @@ -156,6 +156,8 @@ module.exports.globals = { { order: 170, text: 'Logging', icon: 'fas fa-scroll', children: [ + // Activity comes before Audit Log (1.6 FOGPage.php:658-661). + {text: 'Activity', link: '/activity', icon: 'fas fa-clock-rotate-left'}, {text: 'Audit Log', link: '/audit', icon: 'fas fa-clipboard-list'} ] } diff --git a/config/permissions.js b/config/permissions.js index a71f359..d03e5af 100644 --- a/config/permissions.js +++ b/config/permissions.js @@ -6,6 +6,12 @@ module.exports.permissions = { audit: { view: false }, + // The Activity page (GET /activity, POST /api/v1/activity/datatable). The + // key matches no model, so it opens no generic /api/v1/:model route. An + // admin role gets it through api/helpers/permissions/resolve.js, as every leaf. + activity: { + view: false + }, host: { create: false, destroy: false, diff --git a/config/policies.js b/config/policies.js index b465e1c..6a9d321 100644 --- a/config/policies.js +++ b/config/policies.js @@ -39,6 +39,9 @@ module.exports.policies = { // The Audit Log rows (the action checks audit.view itself). It only reads. 'audit/datatable': ['isLoggedIn','isAuthenticated'], + // The Activity rows (the action checks activity.view itself). It only reads. + 'activity/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'], diff --git a/config/routes.js b/config/routes.js index dd7b187..8de94cd 100644 --- a/config/routes.js +++ b/config/routes.js @@ -72,6 +72,10 @@ module.exports.routes = { // must precede POST /api/v1/:model/datatable, or it is read as :model=audit. 'POST /api/v1/audit/datatable': {action: 'audit/datatable', csrf: false}, + // The Activity page rows (GET /activity). A POST read that needs activity.view; + // it must precede POST /api/v1/:model/datatable, or it is read as :model=activity. + 'POST /api/v1/activity/datatable': {action: 'activity/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}, @@ -141,6 +145,9 @@ module.exports.routes = { // The Audit Log page (1.6 AuditManagement), read-only; it needs audit.view. 'GET /audit': {action: 'pages/list/audit'}, + // The Activity page (1.6 ActivityManagement), read-only; it needs activity.view. + 'GET /activity': {action: 'pages/list/activity'}, + // Group Views 'GET /groups': {action: 'pages/list/groups'}, 'GET /groups/create': {action: 'pages/create/groups'}, diff --git a/test/helpers/audit-summary.test.js b/test/helpers/audit-summary.test.js new file mode 100644 index 0000000..ade0fda --- /dev/null +++ b/test/helpers/audit-summary.test.js @@ -0,0 +1,52 @@ +const assert = require('assert'); + +// The Activity summary (api/helpers/audit/summary.js): one plain sentence for an +// AuditLog row. It is a sync helper, called as the app calls it: .with() with +// no .now(). A helper that lost `sync: true` returns a Deferred, and the +// strictEqual assertions fail on it. +describe('Audit summary helper::', () => { + const summary = (row) => sails.helpers.audit.summary.with({row}); + + it('names a PUT on a labeled subject', () => { + assert.strictEqual(summary({ + type: 'access.api', text: 'PUT /api/v1/host/abc', subjectType: 'host', subjectLabel: 'PC-01' + }), 'Updated host "PC-01"'); + }); + + it('names a DELETE with a count and no label', () => { + assert.strictEqual(summary({ + type: 'access.api', text: 'DELETE /api/v1/image', subjectType: 'image', subjectId: '', affectedCount: 3 + }), 'Deleted image (3 records)'); + }); + + it('names a POST with a count of 1 without the count', () => { + assert.strictEqual(summary({ + type: 'access.api', text: 'POST /api/v1/host/bulk', subjectType: 'host', subjectId: '', affectedCount: 1 + }), 'Saved host'); + }); + + it('names a renderable row by its event, subject and text', () => { + assert.strictEqual(summary({ + type: 'agent.token', renderable: true, subjectType: 'agentenrolltoken', subjectLabel: 'lab', text: 'minted, 3 use(s)' + }), 'Agent token, agentenrolltoken "lab": minted, 3 use(s)'); + }); + + it('names agent.enroll, and an unknown event by its type', () => { + assert.strictEqual(summary({type: 'agent.enroll', renderable: true, text: 'enrolled'}), 'Agent enrollment: enrolled'); + assert.strictEqual(summary({type: 'x.y', renderable: true, subjectType: 'host', subjectId: '7', text: 't'}), 'x.y, host #7: t'); + }); + + it('gives a subject with an id and no label as type #id', () => { + assert.strictEqual(summary({type: 'access.api', text: 'PATCH /api/v1/host/7', subjectType: 'host', subjectId: '7'}), 'Updated host #7'); + }); + + it('leaves no trailing space for a row with no subject', () => { + assert.strictEqual(summary({ + type: 'access.page', text: 'POST /account/preferences', subjectType: '', subjectId: '' + }), 'Saved'); + }); + + it('gives the stored text for any other row', () => { + assert.strictEqual(summary({type: 'auth.login', text: 'signed in'}), 'signed in'); + }); +}); diff --git a/test/integration/activity-page.test.js b/test/integration/activity-page.test.js new file mode 100644 index 0000000..6499654 --- /dev/null +++ b/test/integration/activity-page.test.js @@ -0,0 +1,194 @@ +const assert = require('assert'); +const crypto = require('crypto'); +const supertest = require('supertest'); +const support = require('../support/pki'); +const auditWait = require('../support/audit-wait'); +const {waitFor} = auditWait; + +// The Activity page (issue #206): GET /activity and POST /api/v1/activity/datatable, +// behind the activity.view permission. It is a view over the audit trail: a +// successful write that named its record, and the renderable events. The seam +// writes after the response, so a test that expects a row polls for it. A test +// that expects NO row makes its request, then a sentinel request that does write +// a row, waits for the sentinel row, and only then asserts the absence +// (test/integration/audit.test.js). +describe('Activity page::', function () { + this.timeout(120000); + + support.useFixture(); + const app = () => sails.hooks.http.app; + const HTML = ['Accept', 'text/html']; + const AJAX = ['X-Requested-With', 'XMLHttpRequest']; + const RUN = crypto.randomBytes(3).toString('hex'); + const PREFIX = 'mocha-act' + RUN; + const PASSWORD = 'mocha-act-pw'; + const URL = '/api/v1/activity/datatable'; + // A time far ahead of every real row, so the rows of a test sort first. + const FUTURE = 4102444800000; + let seq = 0; + + async function mkUser(label, {isAdmin = false, permissions = {}} = {}) { + const name = `${PREFIX}-${label}`; + const role = await Role.create({name, isAdmin, permissions}).fetch(); + await User.create({username: name, password: PASSWORD, email: `${name}@example.com`, roles: [role.id]}); + return name; + } + + // Signs in as a browser does: a CSRF token for the login form, then the form POST. + async function signIn(username) { + const agent = supertest.agent(app()); + const {body} = await agent.get('/csrfToken').expect(200); + await agent.post('/login').type('form').set(...HTML) + .send({username, password: PASSWORD, _csrf: body._csrf}) + .expect(302).expect('Location', '/'); + return agent; + } + + // A denied GET on a model that no one can read (test/support/audit-wait.js). + const sentinel = (agent, start) => auditWait.sentinel((url) => agent.get(url).set(...AJAX), `${PREFIX}-sentinel-${seq++}`, start); + + const table = (agent, body) => agent.post(URL).set(...AJAX).send(body); + // The rows that a test created: its own createdBy values start with PREFIX. + const mine = (rows) => rows.filter((r) => r.createdBy.startsWith(PREFIX + '-row')); + + let admin; + let limited; + let granted; + let adminName; + + async function cleanup() { + await AuditLog.destroy({createdBy: {startsWith: PREFIX}}); + await User.destroy({username: {startsWith: PREFIX}}); + await Role.destroy({name: {startsWith: PREFIX}}); + } + + before(async () => { + await cleanup(); + adminName = await mkUser('admin', {isAdmin: true}); + const limitedName = await mkUser('limited', {permissions: {stock: {host: {read: true}}}}); + const grantedName = await mkUser('granted', {permissions: {stock: {activity: {view: true}}}}); + admin = await signIn(adminName); + limited = await signIn(limitedName); + granted = await signIn(grantedName); + limited.username = limitedName; + }); + after(cleanup); + + describe('the page', () => { + it('answers 200 with the four headings for an admin', async () => { + const res = await admin.get('/activity').set(...HTML).expect(200); + // The