From 17d9bfaf8ee112c100ce07314dc5dc727e6e8563 Mon Sep 17 00:00:00 2001 From: Tom Elliott Date: Tue, 10 Nov 2026 07:27:35 -0600 Subject: [PATCH] feat(agent): add fog-agent enrollment (POST /agent/v1/enroll, tokens, approvals) A fog-agent enrolls with fog-node exactly as with FOG 1.6: it sends a CSR and its identity, waits while pending, and collects a certificate when an admin approves it, or at once with a valid enroll token or in the deploy window. Statuses, JSON keys and reasons match 1.6, so one agent binary serves both servers. - POST /agent/v1/enroll (public): the 1.6 state machine (200 issued, 202 pending, 403 denied, 426 protocol, 400 csr, 503 signing); host resolution by SMBIOS then MAC; pending hosts as 1.6 creates them. - Enroll tokens: stored as sha256 only; a use is reserved atomically and given back if signing fails. - Admin JSON routes: list enrollments, approve/deny, list/mint/revoke tokens, each with its host permission and apiCsrfGuard. - Host gets server-owned agent fields (agentFingerprint, agentNotAfter, agentVersion, agentCheckin, agentId); create, update, save and the edit page cannot write them. Indexes are made at bootstrap. - The public route caps the CSR (16384 chars) and stores only the contract's identity keys, each capped. - An approved certificate is handed over once even if its host was deleted since, as 1.6 does; the agent then re-enrolls. Co-Authored-By: Claude Opus 5.5 --- api/controllers/agent/decide.js | 48 ++ api/controllers/agent/enroll.js | 200 +++++++ api/controllers/agent/enrollments.js | 35 ++ api/controllers/agent/mint-token.js | 46 ++ api/controllers/agent/revoke-token.js | 21 + api/controllers/agent/tokens.js | 30 + api/controllers/general/create.js | 2 + api/controllers/general/save.js | 2 + api/controllers/general/update.js | 2 + api/controllers/pages/edit.js | 2 + api/helpers/agent/auto-approve.js | 82 +++ api/helpers/agent/create-pending-host.js | 57 ++ api/helpers/agent/ensure-indexes.js | 31 + api/helpers/agent/issue.js | 94 +++ api/helpers/agent/resolve-host.js | 133 +++++ api/helpers/agent/sign-csr.js | 8 +- api/helpers/agent/verify-csr.js | 36 ++ api/lib/agent-pki.js | 19 +- api/models/AgentEnrollToken.js | 40 ++ api/models/AgentEnrollment.js | 77 +++ api/models/Host.js | 39 +- config/bootstrap.js | 4 + config/policies.js | 11 + config/routes.js | 12 + eslint.config.js | 9 +- test/integration/agent-admin.test.js | 358 ++++++++++++ test/integration/agent-enroll.test.js | 710 +++++++++++++++++++++++ test/support/agent-csr.js | 27 + 28 files changed, 2125 insertions(+), 10 deletions(-) create mode 100644 api/controllers/agent/decide.js create mode 100644 api/controllers/agent/enroll.js create mode 100644 api/controllers/agent/enrollments.js create mode 100644 api/controllers/agent/mint-token.js create mode 100644 api/controllers/agent/revoke-token.js create mode 100644 api/controllers/agent/tokens.js create mode 100644 api/helpers/agent/auto-approve.js create mode 100644 api/helpers/agent/create-pending-host.js create mode 100644 api/helpers/agent/ensure-indexes.js create mode 100644 api/helpers/agent/issue.js create mode 100644 api/helpers/agent/resolve-host.js create mode 100644 api/helpers/agent/verify-csr.js create mode 100644 api/models/AgentEnrollToken.js create mode 100644 api/models/AgentEnrollment.js create mode 100644 test/integration/agent-admin.test.js create mode 100644 test/integration/agent-enroll.test.js create mode 100644 test/support/agent-csr.js diff --git a/api/controllers/agent/decide.js b/api/controllers/agent/decide.js new file mode 100644 index 0000000..ef2e00d --- /dev/null +++ b/api/controllers/agent/decide.js @@ -0,0 +1,48 @@ +/** + * POST /api/v1/agent/enrollment/:id/:action + * + * An admin approves or denies a pending fog-agent enrollment (contract 3.6 and + * 6.2). Needs host.update. `action` is approve or deny. + * + * approve signs the STORED CSR, binds the key to the host, and keeps the + * certificate in the row. The agent collects it on its next request. + * deny the row is final, as in 1.6: a denied key is never approved later. + * The pending host that the request created stays. + * + * Errors are {error: ''}: 404 unknown action / no such enrollment, + * 409 enrollment is not pending / enrollment is not bound to a host, 503 signing. + * Success is {id, hostID, state}. + */ +module.exports = { + friendlyName: 'Decide an agent enrollment', + description: 'Approve or deny a pending agent enrollment.', + fn: async function () { + const req = this.req; + const res = this.res; + if (!_.get(req, 'user.permissions.stock.host.update')) { + return res.forbidden(); + } + const action = req.param('action'); + if (action !== 'approve' && action !== 'deny') { + return res.status(404).json({error: 'unknown action'}); + } + const Enrollment = sails.models.agentenrollment; + const row = await Enrollment.findOne({id: req.param('id')}); + if (!row) { return res.status(404).json({error: 'no such enrollment'}); } + if (row.state !== 'pending') { return res.status(409).json({error: 'enrollment is not pending'}); } + + const by = req.user.username; + if (action === 'deny') { + await Enrollment.updateOne({id: row.id}).set({state: 'denied', cert: '', decidedAt: Date.now(), decidedBy: by, decidedVia: 'admin'}); + return res.json({id: row.id, hostID: row.host, state: 'denied'}); + } + + try { + await sails.helpers.agent.issue.with({row, via: 'admin', by, keepCert: true}); + } catch (err) { + if (err.exit === 'notBound') { return res.status(409).json({error: 'enrollment is not bound to a host'}); } + return res.status(503).json({error: 'signing'}); + } + return res.json({id: row.id, hostID: row.host, state: 'issued'}); + } +}; diff --git a/api/controllers/agent/enroll.js b/api/controllers/agent/enroll.js new file mode 100644 index 0000000..2a5df18 --- /dev/null +++ b/api/controllers/agent/enroll.js @@ -0,0 +1,200 @@ +/** + * POST /agent/v1/enroll + * + * A fog-agent sends a CSR and its identity, waits while the request is pending, + * and collects its certificate when an admin approves it, or at once with a valid + * enroll token or just after an imaging. The wire contract is FOG 1.6's, so the + * same agent binary works against both servers: copy the statuses, the JSON keys + * and the strings exactly (briefs/research/2026-11-10-agent-enroll-contract.md, + * section 1.1 for the bodies, 3.1 for the order). The Windows directory feature + * (`features`, `_directoryIdentity`) is out of scope and ignored. + * + * 426 {status: unsupported, reason: protocol} protocol is not 1 + * 400 {status: error, reason: csr} the CSR does not verify + * 403 {status: denied, reason: admin} the row is denied + * 200 {status: issued, host_id, certificate_pem, not_after} + * 202 {status: pending, reason, retry_after: 300} + * 503 {status: error, reason: signing} signing failed, the row stays pending + * + * The lookup key is the fingerprint of the CSR's public key. A repeat is + * answered from the row and never re-resolves the host. The CSR of the FIRST + * request is the one that is signed. No session: the route is public, as boot. + */ +const net = require('net'); +const {leafInfo} = require('../../lib/agent-pki'); + +const RETRY_AFTER = 300; +const MAC = /^(?:[0-9a-f]{2}[:-]){5}[0-9a-f]{2}$/i; + +// The field limits of the 1.6 columns, so a public caller cannot store more. +const text = (value, max) => (typeof value === 'string' ? value.slice(0, max) : ''); + +// Update::normalize: trim, and strip one leading v or V. +const version = (value) => { + const v = text(value, 50).trim(); + return /^[vV]/.test(v) ? v.slice(1) : v; +}; + +// The valid MACs in the Host `macs` form (12 lower-case hex digits), no repeats. +const macsOf = (list) => { + const out = []; + for (const entry of list) { + const mac = entry.replace(/[:-]/g, '').toLowerCase(); + if (!out.includes(mac)) { out.push(mac); } + } + return out; +}; + +// A CSR is about 500 characters (ECDSA P-256) and an RSA-4096 CSR about 1800. +// 16384 leaves room for any real key, and stops a caller from making the +// public route parse and store a huge value. +const MAX_CSR = 16384; +const MAX_MACS = 32; +// The caps for the stored identity fields and the enroll token. No real +// firmware string or minted token (48 hex) comes near them. +const MAX_IDENTITY_FIELD = 256; +const MAX_SMBIOS_VERSION = 32; +const MAX_WARNINGS = 16; +const MAX_TOKEN = 256; + +// The identity keys that the contract defines (section 1.1), and nothing else. +// 1.6 stores the whole object, but this route is public, so the row keeps the +// known keys only, each with a cap. The server-owned _directoryIdentity is +// never accepted. `macs` keeps at most MAX_MACS entries that are valid MACs. +const identityOf = (raw) => { + const given = (raw && typeof raw === 'object' && !Array.isArray(raw)) ? raw : {}; + const out = {}; + for (const key of ['system_uuid', 'system_serial', 'board_serial', 'chassis_asset']) { + out[key] = text(given[key], MAX_IDENTITY_FIELD); + } + if (typeof given.smbios_version === 'string' && given.smbios_version) { out.smbios_version = text(given.smbios_version, MAX_SMBIOS_VERSION); } + out.macs = (Array.isArray(given.macs) ? given.macs : []) + .filter((m) => typeof m === 'string' && MAC.test(m)).slice(0, MAX_MACS); + if (Array.isArray(given.warnings) && given.warnings.length) { + out.warnings = given.warnings.filter((w) => typeof w === 'string').slice(0, MAX_WARNINGS).map((w) => text(w, MAX_IDENTITY_FIELD)); + } + return out; +}; + +module.exports = { + friendlyName: 'Agent enroll', + description: 'Enroll a fog-agent: answer a CSR with pending, issued or denied.', + exits: { + success: {description: 'The answer is in the response.'} + }, + fn: async function () { + const req = this.req; + const res = this.res; + const Enrollment = sails.models.agentenrollment; + const body = (req.body && typeof req.body === 'object' && !Array.isArray(req.body)) ? req.body : {}; + + const pending = (row) => res.status(202).json({status: 'pending', reason: row.reason, retry_after: RETRY_AFTER}); + const issued = (result) => res.status(200).json({ + status: 'issued', + host_id: result.agentId, + certificate_pem: result.pem, + not_after: result.notAfter + }); + const signing = () => res.status(503).json({status: 'error', reason: 'signing'}); + // Run the automatic approval; answer 200, 503 or (when it waits) 202. + const autoApprove = async (row) => { + try { + const result = await sails.helpers.agent.autoApprove.with({row, token: text(body.token, MAX_TOKEN)}); + return result ? issued(result) : pending(row); + } catch (unused) { + return signing(); + } + }; + + // 1. Protocol. + const protocol = (typeof body.protocol === 'number' || typeof body.protocol === 'string') ? Number(body.protocol) : 0; + if (protocol !== 1) { + return res.status(426).json({status: 'unsupported', reason: 'protocol'}); + } + + // 2. The CSR, and its key fingerprint. + const csr = (typeof body.csr_pem === 'string' && body.csr_pem.length <= MAX_CSR) ? body.csr_pem : ''; + let fingerprint; + try { + await sails.helpers.agent.verifyCsr(csr); + fingerprint = sails.helpers.agent.keyFingerprint(csr); + } catch (unused) { + return res.status(400).json({status: 'error', reason: 'csr'}); + } + const identity = identityOf(body.identity); + const agentVersion = version(body.agent_version); + const hostname = text(body.hostname, 191); + const os = text(body.os, 20); + const arch = text(body.arch, 20); + const remoteIp = net.isIP(req.ip || '') ? req.ip : ''; + + // The state machine of contract 2.1, for a row that exists. + const answerFromRow = async (found) => { + if (found.state === 'denied') { + await Enrollment.updateOne({id: found.id}).set({remoteIp, agentVersion}); + return res.status(403).json({status: 'denied', reason: 'admin'}); + } + if (found.state === 'issued' && found.cert !== '') { + // Approved since the last request. Hand the certificate over once, as + // 1.6 does, even if the host is gone since (the agent then gets 401 + // unknown_certificate and enrolls again). + // The 1.6 _issuedPayload takes host_id and not_after from the host. The + // host may be gone, so leafInfo reads both from the stored leaf: the CN + // number (the agent number the agent stores as host_id) and notAfter. + // Parse before clearing, so a bad stored leaf never loses the cert. + const leaf = leafInfo(found.cert); + await Enrollment.updateOne({id: found.id}).set({cert: ''}); + return issued({agentId: leaf.agentId, pem: found.cert, notAfter: leaf.notAfter}); + } + if (found.state === 'issued') { + // The agent lost its certificate but kept its key. An admin looks at it. + return pending(await Enrollment.updateOne({id: found.id}).set({state: 'pending', reason: 'reissue'})); + } + // Still pending: refresh the row, and re-check the automatic paths. A + // token may be valid now, or the deploy may have finished. + return await autoApprove(await Enrollment.updateOne({id: found.id}).set({ + agentVersion, hostname, os, remoteIp + })); + }; + + // 4. A row for this key answers the request. + let row = await Enrollment.findOne({fingerprint}); + if (row) { return await answerFromRow(row); } + + // 3. The valid MACs, then 5. the first contact for this key. + const macs = macsOf(identity.macs); + const resolved = await sails.helpers.agent.resolveHost.with({identity, macs}); + // Unknown machine with no MAC: no pending host (a host needs a MAC to be addressed). + const reason = (resolved.reason === 'unknown-host' && !macs.length) ? 'no-mac' : resolved.reason; + try { + row = await Enrollment.create({ + host: resolved.hostId, + fingerprint, + csr, + identity, + hostname, + os, + arch, + agentVersion, + remoteIp, + reason, + state: 'pending', + cert: '' + }).fetch(); + } catch (err) { + // Two first requests for one key: the unique index kept the first row. + if (err && err.code === 'E_UNIQUE') { + row = await Enrollment.findOne({fingerprint}); + return await answerFromRow(row); + } + throw err; + } + if (reason === 'unknown-host') { + const host = await sails.helpers.agent.createPendingHost.with({ + hostname, fingerprint, macs, smbios: resolved.smbios + }); + row = await Enrollment.updateOne({id: row.id}).set({host: host.id}); + } + return await autoApprove(row); + } +}; diff --git a/api/controllers/agent/enrollments.js b/api/controllers/agent/enrollments.js new file mode 100644 index 0000000..95cf4bd --- /dev/null +++ b/api/controllers/agent/enrollments.js @@ -0,0 +1,35 @@ +/** + * GET /api/v1/agent/enrollments + * + * The pending fog-agent enrollment requests, oldest first, for the admin + * (contract 6.1 and 6.2). Needs host.read. Never returns the CSR or the cert. + * These admin routes follow fog-node's conventions (camelCase, ms timestamps), + * not the agent wire format. + */ +module.exports = { + friendlyName: 'Agent enrollments', + description: 'List the pending agent enrollment requests.', + fn: async function () { + const res = this.res; + if (!_.get(this.req, 'user.permissions.stock.host.read')) { + return res.forbidden(); + } + const rows = await sails.models.agentenrollment.find({state: 'pending'}).sort('createdAt ASC'); + return res.json({ + data: rows.map((row) => ({ + id: row.id, + hostID: row.host, + hostname: row.hostname, + os: row.os, + arch: row.arch, + agentVersion: row.agentVersion, + remoteIp: row.remoteIp, + reason: row.reason, + fingerprint: row.fingerprint, + identity: row.identity, + createdAt: row.createdAt, + updatedAt: row.updatedAt + })) + }); + } +}; diff --git a/api/controllers/agent/mint-token.js b/api/controllers/agent/mint-token.js new file mode 100644 index 0000000..b326d1e --- /dev/null +++ b/api/controllers/agent/mint-token.js @@ -0,0 +1,46 @@ +/** + * POST /api/v1/agent/token + * + * Mint a fog-agent enrollment token (contract 2.2 and 6.2). Needs host.create. + * Body {name, uses (default 1), expires (ms, or a date string)}, validated as + * 1.6 does: name 1 to 191 characters, uses at least 1 or -1 (unlimited), + * expires in the future. Answers {id, name, token, expires}. The token is 48 hex + * characters from crypto.randomBytes(24) and is shown only here. Only its + * sha256 is stored. + */ +const crypto = require('crypto'); + +module.exports = { + friendlyName: 'Mint an agent token', + description: 'Create an enrollment token and show it once.', + fn: async function () { + const req = this.req; + const res = this.res; + if (!_.get(req, 'user.permissions.stock.host.create')) { + return res.forbidden(); + } + const bad = (error) => res.status(400).json({error}); + + const body = req.body || {}; + const name = typeof body.name === 'string' ? body.name.trim() : ''; + if (name === '' || name.length > 191) { return bad('name is required, at most 191 characters'); } + + const given = body.uses; + const uses = (given === undefined || given === null || given === '') ? 1 : Number(given); + if (!Number.isInteger(uses) || (uses < 1 && uses !== -1)) { return bad('uses must be at least 1, or -1 for unlimited'); } + + const raw = body.expires; + const expires = typeof raw === 'number' ? raw : (typeof raw === 'string' ? Date.parse(raw) : NaN); + if (!Number.isFinite(expires) || expires <= Date.now()) { return bad('expires must be a date and time in the future'); } + + const token = crypto.randomBytes(24).toString('hex'); + const row = await sails.models.agentenrolltoken.create({ + name, + hash: sails.models.agentenrolltoken.hashOf(token), + uses, + expires, + createdBy: req.user.username + }).fetch(); + return res.json({id: row.id, name, token, expires}); + } +}; diff --git a/api/controllers/agent/revoke-token.js b/api/controllers/agent/revoke-token.js new file mode 100644 index 0000000..6bbc295 --- /dev/null +++ b/api/controllers/agent/revoke-token.js @@ -0,0 +1,21 @@ +/** + * DELETE /api/v1/agent/token/:id + * + * Revoke a fog-agent enrollment token: the row goes, so its hash can never + * match again (contract 2.2 and 6.2). Needs host.destroy. 404 {error: 'no such + * token'} when it does not exist; else {id}. + */ +module.exports = { + friendlyName: 'Revoke an agent token', + description: 'Delete an enrollment token.', + fn: async function () { + const req = this.req; + const res = this.res; + if (!_.get(req, 'user.permissions.stock.host.destroy')) { + return res.forbidden(); + } + const row = await sails.models.agentenrolltoken.destroyOne({id: req.param('id')}); + if (!row) { return res.status(404).json({error: 'no such token'}); } + return res.json({id: row.id}); + } +}; diff --git a/api/controllers/agent/tokens.js b/api/controllers/agent/tokens.js new file mode 100644 index 0000000..1c39e95 --- /dev/null +++ b/api/controllers/agent/tokens.js @@ -0,0 +1,30 @@ +/** + * GET /api/v1/agent/tokens + * + * The fog-agent enrollment tokens, for the admin (contract 2.2 and 6.2). Needs + * host.read. `state` is spent (no use left), else expired, else active. It + * never returns the hash. + */ +module.exports = { + friendlyName: 'Agent tokens', + description: 'List the agent enrollment tokens.', + fn: async function () { + const res = this.res; + if (!_.get(this.req, 'user.permissions.stock.host.read')) { + return res.forbidden(); + } + const now = Date.now(); + const rows = await sails.models.agentenrolltoken.find().sort('createdAt ASC'); + return res.json({ + data: rows.map((row) => ({ + id: row.id, + name: row.name, + uses: row.uses, + expires: row.expires, + createdBy: row.createdBy, + createdAt: row.createdAt, + state: row.uses === 0 ? 'spent' : (row.expires < now ? 'expired' : 'active') + })) + }); + } +}; diff --git a/api/controllers/general/create.js b/api/controllers/general/create.js index 5128917..e246f49 100644 --- a/api/controllers/general/create.js +++ b/api/controllers/general/create.js @@ -25,6 +25,8 @@ module.exports = { let model = params.model; // API-token requests may never write credentials (password / apiTokenHash). if (req.authVia === 'apitoken') { delete params.password; delete params.apiTokenHash; } + // The host's agent fields are server-owned: only the enroll code writes them. + if (model === 'host') { params = _.omit(params, sails.models.host.serverOwned); } // A Group name that is not text (400) or is taken without case (409), or // a host's groups change that the caller may not make (403). let check = await sails.helpers.group.checkSave.with({model, values: params, permissions: req.user.permissions}); diff --git a/api/controllers/general/save.js b/api/controllers/general/save.js index b7f88ed..71f9e64 100644 --- a/api/controllers/general/save.js +++ b/api/controllers/general/save.js @@ -34,6 +34,8 @@ module.exports = { // Build the values from the body, dropping non-attribute keys. let values = _.omit(req.allParams(), ['model', '_csrf', 'id', '__primac']); + // The host's agent fields are server-owned: only the enroll code writes them. + if (model === 'host') { values = _.omit(values, sails.models.host.serverOwned); } // API-token requests may never write credentials (password / apiTokenHash). if (req.authVia === 'apitoken') { delete values.password; delete values.apiTokenHash; } diff --git a/api/controllers/general/update.js b/api/controllers/general/update.js index 5e89436..e24ac32 100644 --- a/api/controllers/general/update.js +++ b/api/controllers/general/update.js @@ -26,6 +26,8 @@ module.exports = { let id = params.id; // API-token requests may never write credentials (password / apiTokenHash). if (req.authVia === 'apitoken') { delete params.password; delete params.apiTokenHash; } + // The host's agent fields are server-owned: only the enroll code writes them. + if (model === 'host') { params = _.omit(params, sails.models.host.serverOwned); } // A Group name that is not text (400) or is taken without case (409), or // a host's groups change that the caller may not make (403). oldGroup is // the Group before a rename. diff --git a/api/controllers/pages/edit.js b/api/controllers/pages/edit.js index a37fb73..da29a4e 100644 --- a/api/controllers/pages/edit.js +++ b/api/controllers/pages/edit.js @@ -54,6 +54,8 @@ module.exports = { let model = plural.replace(/s$/, ''); let id = req.param('id'); let skip = ['id', 'createdAt', 'updatedAt', 'password', 'permissions']; + // The agent fields are server-owned: the edit page shows none of them. + if (model === 'host') { skip = skip.concat(sails.models.host.serverOwned); } if (!model || !sails.models[model]) { throw 'notFound'; diff --git a/api/helpers/agent/auto-approve.js b/api/helpers/agent/auto-approve.js new file mode 100644 index 0000000..5a96579 --- /dev/null +++ b/api/helpers/agent/auto-approve.js @@ -0,0 +1,82 @@ +/** + * Try the automatic approval of a pending fog-agent enrollment and, when one + * applies, issue the certificate (contract 3.5, without the directory feature + * guard; Enrollment::_autoApproval and _issueNow). In this order: + * + * 1. Token: the trimmed `token` is not empty, and its sha256 hex finds a row + * that has not expired and has a use left. One use is reserved with a + * single conditional update, so two requests that race for the last use + * cannot both win. A use of -1 is unlimited and never changes. If the + * signing then fails, the use is given back, so a failed sign spends + * nothing (the 1.6 quirk, fixed). + * 2. Deploy: the row is bound, its reason is known-host-no-agent or rebind, + * and the host's `deployed` time is within the Setting + * FOG_AGENT_ENROLL_DEPLOY_WINDOW hours before now (default 24, below 1 + * disables). Nothing in fog-node writes `deployed` yet. + * 3. Otherwise the request waits. + * + * A row with no host (no-mac) never auto-approves. + * + * Inputs: row (an AgentEnrollment record), token (any text, '' for none). + * Output: null when the request waits, else {pem, agentId, notAfter} from issue. + * Exit signing: an approval applied but the issue failed. The row stays pending. + * + * Usage: let issued = await sails.helpers.agent.autoApprove.with({row, token}) + */ +const HOUR_MS = 60 * 60 * 1000; +const DEFAULT_WINDOW_HOURS = 24; + +module.exports = { + friendlyName: 'Auto-approve an agent enrollment', + description: 'Issue the certificate at once when a valid token or a recent deploy vouches for the host.', + inputs: { + row: {type: 'ref', required: true}, + token: {type: 'string', defaultsTo: ''} + }, + exits: { + success: {outputType: 'ref', description: 'null, or {pem, agentId, notAfter}.'}, + signing: {description: 'The issue failed.'} + }, + fn: async function ({row, token}) { + if (!row.host) { return null; } + + // Reserve a token use. + const tokens = sails.getDatastore(sails.models.agentenrolltoken.datastore).manager.collection(sails.models.agentenrolltoken.tableName); + const secret = token.trim(); + const hash = sails.models.agentenrolltoken.hashOf(secret); + let reserved = false; + let via = ''; + if (secret) { + const now = Date.now(); + const found = await tokens.findOne({hash}); + if (found && found.expires > now) { + if (found.uses === -1) { + via = 'token'; + } else { + const taken = await tokens.updateOne({hash, expires: {$gt: now}, uses: {$gt: 0}}, {$inc: {uses: -1}}); + reserved = taken.modifiedCount === 1; + if (reserved) { via = 'token'; } + } + } + } + + if (!via && ['known-host-no-agent', 'rebind'].includes(row.reason)) { + const setting = await sails.models.setting.findOne({name: 'FOG_AGENT_ENROLL_DEPLOY_WINDOW'}); + const window = setting ? Number(setting.value) : DEFAULT_WINDOW_HOURS; + const hours = Number.isNaN(window) ? DEFAULT_WINDOW_HOURS : window; + const host = hours >= 1 ? await sails.models.host.findOne({id: row.host}) : undefined; + const deployed = host ? Date.parse(host.deployed) : NaN; + if (!Number.isNaN(deployed) && deployed <= Date.now() && Date.now() - deployed <= hours * HOUR_MS) { + via = 'deploy'; + } + } + if (!via) { return null; } + + try { + return await sails.helpers.agent.issue.with({row, via, by: '', keepCert: false}); + } catch (unused) { + if (reserved) { await tokens.updateOne({hash}, {$inc: {uses: 1}}); } + throw 'signing'; + } + } +}; diff --git a/api/helpers/agent/create-pending-host.js b/api/helpers/agent/create-pending-host.js new file mode 100644 index 0000000..245c519 --- /dev/null +++ b/api/helpers/agent/create-pending-host.js @@ -0,0 +1,57 @@ +/** + * Create the pending host for an unknown fog-agent machine (contract 3.4; + * Enrollment::_createPendingHost). The caller binds the enrollment row to it. + * + * The name is the request hostname when it passes the Host name rule and has at + * most 15 characters (the NetBIOS limit), else `agent-`. While a host has that name (without case), the helper appends + * -1, -2, ... and cuts the base so the name stays at most 15 characters. + * + * Inputs: + * hostname the request hostname (any text) + * fingerprint the key fingerprint + * macs the valid MACs, 12 lower-case hex digits each (at least one) + * smbios {guid, serial, asset}: the usable values from resolveHost + * + * Output: the new Host record. + * + * Usage: let host = await sails.helpers.agent.createPendingHost.with({hostname, fingerprint, macs, smbios}) + */ +const MAX_NAME = 15; + +module.exports = { + friendlyName: 'Create a pending agent host', + description: 'Create the pending Host for a machine that no host matched.', + inputs: { + hostname: {type: 'string', defaultsTo: ''}, + fingerprint: {type: 'string', required: true}, + macs: {type: 'ref', required: true}, + smbios: {type: 'ref', required: true} + }, + exits: { + success: {outputType: 'ref', description: 'The new Host record.'} + }, + fn: async function ({hostname, fingerprint, macs, smbios}) { + const Host = sails.models.host; + const base = (hostname.length <= MAX_NAME && Host.nameRegex.test(hostname)) ? + hostname : 'agent-' + fingerprint.slice(0, 8); + // Host names are unique without case. Count with the case-insensitive collation. + const coll = sails.getDatastore(Host.datastore).manager.collection(Host.tableName); + const taken = async (name) => (await coll.countDocuments({name}, {collation: {locale: 'en', strength: 2}})) > 0; + + let name = base; + for (let n = 1; await taken(name); n++) { + const suffix = '-' + n; + name = base.slice(0, MAX_NAME - suffix.length) + suffix; + } + return Host.create({ + name, + macs, + guid: smbios.guid, + serial: smbios.serial, + asset: smbios.asset, + pending: true, + description: 'Pending Registration created by FOG_AGENT' + }).fetch(); + } +}; diff --git a/api/helpers/agent/ensure-indexes.js b/api/helpers/agent/ensure-indexes.js new file mode 100644 index 0000000..485efd3 --- /dev/null +++ b/api/helpers/agent/ensure-indexes.js @@ -0,0 +1,31 @@ +/** + * The indexes that fog-agent enrollment needs. The models use `migrate: 'safe'`, + * so the ORM creates no index and `unique: true` enforces nothing by itself. + * config/bootstrap.js runs this at each lift. createIndex does nothing when the + * index exists, so a new install and an upgraded install both get them (the + * Group precedent: api/helpers/group/ensure-index.js). No schema revision. + * + * agentenrollment.fingerprint unique: one row per key + * agentenrolltoken.hash unique: one row per token + * host.agentFingerprint plain: the lookup of a host by its key + * host.agentId unique, partial on agentId > 0. Waterline + * writes 0 for an omitted number, so 0 must not + * be indexed, or a second host with no agent + * would collide. + * + * Usage: await sails.helpers.agent.ensureIndexes() + */ +module.exports = { + friendlyName: 'Ensure the agent indexes', + description: 'Create the fog-agent enrollment indexes when they do not exist.', + exits: { + success: {description: 'The indexes exist.'} + }, + fn: async function () { + const collection = (model) => sails.getDatastore(model.datastore).manager.collection(model.tableName); + await collection(sails.models.agentenrollment).createIndex({fingerprint: 1}, {unique: true}); + await collection(sails.models.agentenrolltoken).createIndex({hash: 1}, {unique: true}); + await collection(sails.models.host).createIndex({agentFingerprint: 1}); + await collection(sails.models.host).createIndex({agentId: 1}, {unique: true, partialFilterExpression: {agentId: {$gt: 0}}}); + } +}; diff --git a/api/helpers/agent/issue.js b/api/helpers/agent/issue.js new file mode 100644 index 0000000..96ab3d2 --- /dev/null +++ b/api/helpers/agent/issue.js @@ -0,0 +1,94 @@ +/** + * Issue the certificate for a bound fog-agent enrollment (contract 3.6; + * Enrollment::_issue). Used by the automatic paths (api/helpers/agent/ + * auto-approve.js) and by the admin approve (api/controllers/agent/decide.js). + * + * It signs the STORED CSR (the first request's, not the latest) with + * signCsr(csr, String(agentId)). The host number `agentId` is assigned here, + * once, when the host first gets an agent: the next value of the counter + * document {_id: 'agentId'} in the `counters` collection. A host that has an + * agentId keeps it. A number is never reused, so a failed sign can leave a gap. + * + * On the host: agentFingerprint, agentNotAfter (UTC), agentVersion (from the + * row), agentCheckin (now), pending false. On the row: state issued, decidedAt, + * decidedBy, decidedVia. `keepCert` true (admin approve) stores the PEM in the + * row's `cert` for the agent's next request. False (automatic) answers the + * agent in the same request and leaves `cert` ''. + * + * Inputs: row (an AgentEnrollment record), via (token, deploy or admin), by + * (the admin's user name, '' when automatic), keepCert. + * Output {pem, agentId, notAfter}: pem is the leaf then the agent CA. + * + * Exits: + * notBound the row has no host, or the host no longer exists + * signing the CSR could not be signed (no PKI, root mismatch, bad CSR) + * + * Usage: let {pem, agentId, notAfter} = await sails.helpers.agent.issue.with({row, via, by, keepCert}) + */ +const {leafInfo} = require('../../lib/agent-pki'); +const ObjectId = require('mongodb').ObjectID; + +module.exports = { + friendlyName: 'Issue an agent certificate', + description: 'Sign the stored CSR for the bound host and record the decision.', + inputs: { + row: {type: 'ref', required: true}, + via: {type: 'string', required: true}, + by: {type: 'string', defaultsTo: ''}, + keepCert: {type: 'boolean', defaultsTo: false} + }, + exits: { + success: {outputType: 'ref', description: '{pem, agentId, notAfter}'}, + notBound: {description: 'The row has no host, or the host is gone.'}, + signing: {description: 'The signing failed.'} + }, + fn: async function ({row, via, by, keepCert}) { + const Host = sails.models.host; + const host = row.host ? await Host.findOne({id: row.host}) : undefined; + if (!host) { throw 'notBound'; } + + let agentId = host.agentId; + if (!(agentId > 0)) { + const manager = sails.getDatastore(Host.datastore).manager; + const counter = await manager.collection('counters') + .findOneAndUpdate({_id: 'agentId'}, {$inc: {seq: 1}}, {upsert: true, returnDocument: 'after'}); + agentId = counter.value.seq; + // Set it only while the host has none, so two issues for one host agree. + const set = await manager.collection(Host.tableName).updateOne( + {_id: new ObjectId(host.id), $or: [{agentId: {$exists: false}}, {agentId: 0}]}, + {$set: {agentId}}); + if (set.modifiedCount !== 1) { + const again = await Host.findOne({id: host.id}); + if (!again || !(again.agentId > 0)) { throw 'notBound'; } + agentId = again.agentId; + } + } + + let signed; + try { + signed = await sails.helpers.agent.signCsr.with({csrPem: row.csr, hostId: String(agentId)}); + } catch (err) { + sails.log.warn(`agent enroll: signing for host ${host.id} failed: ${err.exit || err.message}`); + throw 'signing'; + } + const pem = signed.leafPem + signed.chainPem; + const {notAfter} = leafInfo(signed.leafPem); + + const now = Date.now(); + await Host.updateOne({id: host.id}).set({ + agentFingerprint: row.fingerprint, + agentNotAfter: notAfter, + agentVersion: row.agentVersion, + agentCheckin: now, + pending: false + }); + await sails.models.agentenrollment.updateOne({id: row.id}).set({ + state: 'issued', + decidedAt: now, + decidedBy: by, + decidedVia: via, + cert: keepCert ? pem : '' + }); + return {pem, agentId, notAfter}; + } +}; diff --git a/api/helpers/agent/resolve-host.js b/api/helpers/agent/resolve-host.js new file mode 100644 index 0000000..a5a1a30 --- /dev/null +++ b/api/helpers/agent/resolve-host.js @@ -0,0 +1,133 @@ +/** + * Resolve the host that a first fog-agent enroll request belongs to, as FOG 1.6 + * does (contract 3.2, the non-feature path; Enrollment::_resolve). Only a + * non-pending host can resolve, so a pending host that an earlier request + * created is never found again, and a second key with the same MAC gets its + * own pending host (1.6 does the same). + * + * SMBIOS first, unless the Setting FOG_HOST_IDENTIFY_SMBIOS is `off`. Each + * non-pending host scores +1 for a guid that equals system_uuid, +1 for a serial + * that equals system_serial, and +1 for an asset that equals chassis_asset only + * when one of those two matched. The unique top score of 1 or more wins. A tie + * is no match. Then the MACs: one host wins, or the one with the most matching + * MACs, and a tie is no match. fog-node keeps no board serial, so board_serial + * is not matched. + * + * Inputs: + * identity the request `identity` object + * macs the valid MACs, 12 lower-case hex digits each + * + * Output {hostId, reason, smbios}. + * hostId the winning host's id, or '' when none resolved + * reason unknown-host, identity-conflict, rebind or known-host-no-agent + * smbios {guid, serial, asset}: the usable canonical values, for a new pending host + * + * Usage: let {hostId, reason, smbios} = await sails.helpers.agent.resolveHost.with({identity, macs}) + */ +// The values that mean "the firmware did not say". Copied from PLACEHOLDERS in +// /var/www/html/fog-1.6/src/Base/SmbiosIdentity.php (compared without case). +const PLACEHOLDERS = [ + '00020003-0004-0005-0006-000700080009', + '12345678-1234-5678-90AB-CDDEEFAABBCC', + '123456789', + 'Not Present', + 'Not Settable', + 'Not Specified', + 'Not Applicable', + 'Not Available', + 'None', + 'N/A', + 'Unknown', + 'Default string', + 'To be filled by O.E.M.', + 'To Be Set By OEM', + 'Enter Serial', + 'Type2 - Board Serial Number', + 'Base Board Serial Number', + 'System Serial Number', + 'Chassis Serial Number', + 'Chassis Asset Tag', + 'Asset Tag', + 'No Asset Tag', + 'No Asset Information', + '.PCIE2' +].map((p) => p.toLowerCase()); + +// SmbiosIdentity::canonicalize: trim, and collapse whitespace runs to one space. +const canonicalize = (value) => (typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : ''); + +// SmbiosIdentity::isUsable. The value is canonical. Returns '' for a value to drop. +const usable = (value) => { + if (value === '' || PLACEHOLDERS.includes(value.toLowerCase())) { return ''; } + // One repeated character, once "-", "/" and spaces are removed. + const bare = value.replace(/[-/ ]/g, ''); + return (bare === '' || /^(.)\1*$/i.test(bare)) ? '' : value; +}; + +// The id of the unique entry with the top score (1 or more), or '' on a tie or +// when there is none. `scores` maps a host id to its score. +const winner = (scores) => { + const ranked = Object.entries(scores).sort((a, b) => b[1] - a[1]); + if (!ranked.length || ranked[0][1] < 1) { return ''; } + if (ranked.length > 1 && ranked[1][1] === ranked[0][1]) { return ''; } + return ranked[0][0]; +}; + +module.exports = { + friendlyName: 'Resolve an agent host', + description: 'Find the host that a first enroll request belongs to, by SMBIOS and then by MAC.', + inputs: { + identity: {type: 'ref', required: true, description: 'The request identity object.'}, + macs: {type: 'ref', required: true, description: 'The valid MACs, 12 lower-case hex digits each.'} + }, + exits: { + success: {outputType: 'ref', description: '{hostId, reason, smbios}'} + }, + fn: async function ({identity, macs}) { + const smbios = { + guid: usable(canonicalize(identity.system_uuid)), + serial: usable(canonicalize(identity.system_serial)), + asset: usable(canonicalize(identity.chassis_asset)) + }; + const coll = sails.getDatastore(sails.models.host.datastore).manager.collection(sails.models.host.tableName); + const docs = {}; + + // The Host model stores guid, serial and asset in lower case. + let smbiosId = ''; + const setting = await sails.models.setting.findOne({name: 'FOG_HOST_IDENTIFY_SMBIOS'}); + const smbiosOff = setting && String(setting.value).trim().toLowerCase() === 'off'; + if (!smbiosOff && (smbios.guid || smbios.serial)) { + const guid = smbios.guid.toLowerCase(); + const serial = smbios.serial.toLowerCase(); + const asset = smbios.asset.toLowerCase(); + const or = []; + if (guid) { or.push({guid}); } + if (serial) { or.push({serial}); } + const scores = {}; + for (const doc of await coll.find({pending: {$ne: true}, $or: or}).toArray()) { + const id = String(doc._id); + docs[id] = doc; + const firmware = (guid && doc.guid === guid ? 1 : 0) + (serial && doc.serial === serial ? 1 : 0); + scores[id] = firmware + (firmware && asset && doc.asset === asset ? 1 : 0); + } + smbiosId = winner(scores); + } + + let macId = ''; + if (macs.length) { + const scores = {}; + for (const doc of await coll.find({pending: {$ne: true}, macs: {$in: macs}}).toArray()) { + const id = String(doc._id); + docs[id] = doc; + scores[id] = (doc.macs || []).filter((m) => macs.includes(m)).length; + } + macId = winner(scores); + } + + const hostId = smbiosId || macId; + if (!hostId) { return {hostId: '', reason: 'unknown-host', smbios}; } + // Firmware and MACs name different hosts: keep the firmware's host. + if (smbiosId && macId && smbiosId !== macId) { return {hostId, reason: 'identity-conflict', smbios}; } + return {hostId, reason: docs[hostId].agentFingerprint ? 'rebind' : 'known-host-no-agent', smbios}; + } +}; diff --git a/api/helpers/agent/sign-csr.js b/api/helpers/agent/sign-csr.js index 6e887df..145a948 100644 --- a/api/helpers/agent/sign-csr.js +++ b/api/helpers/agent/sign-csr.js @@ -45,12 +45,10 @@ module.exports = { // Same check as the 1.6 helper. It also keeps the subject text safe. if (!/^[0-9]{1,10}$/.test(hostId)) throw 'badHostId'; + // The marker, the parse and the self-signature: the check that enroll makes. let csr; try { - if (!pki.isCsrPem(csrPem)) throw new Error('not a CSR'); - csr = new x509.Pkcs10CertificateRequest(csrPem); - // Proof of possession: the CSR is signed by the key it carries. - if (!(await csr.verify())) throw new Error('bad signature'); + csr = await sails.helpers.agent.verifyCsr(csrPem); } catch (unused) { throw 'badCsr'; } @@ -90,7 +88,7 @@ module.exports = { const ca = new x509.X509Certificate(caPem); const leaf = await x509.X509CertificateGenerator.create({ serialNumber: pki.randomSerial(), - subject: pki.subjectOf(`fog-agent host ${hostId}`, 'FOG Agent'), + subject: pki.subjectOf(pki.agentCn(hostId), 'FOG Agent'), issuer: ca.subjectName, notBefore: new Date(), notAfter: new Date(Date.now() + 365 * pki.DAY_MS), diff --git a/api/helpers/agent/verify-csr.js b/api/helpers/agent/verify-csr.js new file mode 100644 index 0000000..9026746 --- /dev/null +++ b/api/helpers/agent/verify-csr.js @@ -0,0 +1,36 @@ +/** + * Check a fog-agent CSR: it carries the CSR marker, it parses, and it is signed + * by the key it carries (proof of possession). signCsr and the enroll route + * share this check, so a CSR that passes at enroll also passes at approve. + * + * Input: the CSR, PEM text. + * Output: the parsed Pkcs10CertificateRequest (@peculiar/x509). + * Exit invalid: the text is not a CSR, does not parse, or its signature fails. + * + * Usage: let csr = await sails.helpers.agent.verifyCsr(csrPem) + */ +const x509 = require('@peculiar/x509'); +const pki = require('../../lib/agent-pki'); + +module.exports = { + friendlyName: 'Verify an agent CSR', + description: 'Check the marker, the parse and the self-signature of a CSR.', + inputs: { + csrPem: {type: 'string', required: true, description: 'The CSR, PEM text.'} + }, + exits: { + success: {outputType: 'ref', description: 'The parsed CSR.'}, + invalid: {description: 'Not a CSR, or its signature does not verify.'} + }, + fn: async function ({csrPem}) { + try { + if (!pki.isCsrPem(csrPem)) throw new Error('not a CSR'); + const csr = new x509.Pkcs10CertificateRequest(csrPem); + // Proof of possession: the CSR is signed by the key it carries. + if (!(await csr.verify())) throw new Error('bad signature'); + return csr; + } catch (unused) { + throw 'invalid'; + } + } +}; diff --git a/api/lib/agent-pki.js b/api/lib/agent-pki.js index 2a2f91e..b2a1fc5 100644 --- a/api/lib/agent-pki.js +++ b/api/lib/agent-pki.js @@ -62,4 +62,21 @@ const ROOT_SETTING_DESCRIPTION = 'The SHA-256 fingerprint of the root CA that en // The fingerprint of a certificate, as Node prints it (colon hex, upper case). const fingerprintOf = (pem) => new crypto.X509Certificate(pem).fingerprint256; -module.exports = {DAY_MS, CLIENT_AUTH, RSA, ROOT_SETTING, ROOT_SETTING_DESCRIPTION, fingerprintOf, isCsrPem, randomSerial, subjectOf, importPair, verifies}; +// The agent leaf CN, "fog-agent host " (contract 4.2). signCsr writes it and +// leafInfo reads it back, so the text lives here once. +const AGENT_CN_PREFIX = 'fog-agent host '; +const agentCn = (hostId) => `${AGENT_CN_PREFIX}${hostId}`; +const AGENT_CN_RX = new RegExp(`^CN=${AGENT_CN_PREFIX}(\\d+)$`, 'm'); + +// The host number and expiry of an agent leaf. `agentId` is null when the CN +// is not an agent CN. `notAfter` is UTC "YYYY-MM-DD HH:MM:SS", the 1.6 format. +const leafInfo = (pem) => { + const leaf = new crypto.X509Certificate(pem); + const cn = AGENT_CN_RX.exec(leaf.subject); + return { + agentId: cn ? Number(cn[1]) : null, + notAfter: new Date(Date.parse(leaf.validTo)).toISOString().slice(0, 19).replace('T', ' ') + }; +}; + +module.exports = {DAY_MS, CLIENT_AUTH, RSA, ROOT_SETTING, ROOT_SETTING_DESCRIPTION, fingerprintOf, isCsrPem, randomSerial, subjectOf, importPair, verifies, agentCn, leafInfo}; diff --git a/api/models/AgentEnrollToken.js b/api/models/AgentEnrollToken.js new file mode 100644 index 0000000..22317c7 --- /dev/null +++ b/api/models/AgentEnrollToken.js @@ -0,0 +1,40 @@ +/** + * AgentEnrollToken.js + * + * A fog-agent enrollment token (contract 2.2). Only the sha256 of the secret is + * stored; the secret is shown once, at mint. An agent that sends a valid token + * is issued a certificate at once (api/helpers/agent/auto-approve.js). + * + * Not generic CRUD: config/permissions.js has no stock entry for it. + */ +const crypto = require('crypto'); + +module.exports = { + // The stored form of a token secret: the sha256 hex of the trimmed text. + // The one place that trims, so mint and enroll agree (AgentEnrollToken.hashOf). + hashOf: (token) => crypto.createHash('sha256').update(String(token).trim()).digest('hex'), + attributes: { + name: { + type: 'string' + }, + // sha256 hex of the token secret. + hash: { + type: 'string', + required: true, + unique: true + }, + // Uses left. -1 is unlimited until `expires`. + uses: { + type: 'number', + isInteger: true, + defaultsTo: 1 + }, + // ms + expires: { + type: 'number' + }, + createdBy: { + type: 'string' + } + } +}; diff --git a/api/models/AgentEnrollment.js b/api/models/AgentEnrollment.js new file mode 100644 index 0000000..2d03ae2 --- /dev/null +++ b/api/models/AgentEnrollment.js @@ -0,0 +1,77 @@ +/** + * AgentEnrollment.js + * + * One fog-agent enrollment request, keyed by the fingerprint of the agent's + * public key (one row per key). It is the memory of what was decided about that + * key, so a repeat request is answered from the row. FOG 1.6 keeps the same + * record in the agentEnrollment table (contract 2.1). The state machine is in + * api/controllers/agent/enroll.js. + * + * Not generic CRUD: config/permissions.js has no stock entry for it, so the + * /api/v1/:model routes refuse it. The admin routes are api/controllers/agent/. + */ +module.exports = { + attributes: { + // The id of the bound Host, or '' until the row is bound. + host: { + type: 'string', + defaultsTo: '' + }, + // sha256 hex of the public key PEM (api/helpers/agent/key-fingerprint.js). + fingerprint: { + type: 'string', + required: true, + unique: true + }, + // The CSR of the FIRST request. Approval signs this one. + csr: { + type: 'string', + required: true + }, + // The identity block as the agent sent it. + identity: { + type: 'json' + }, + hostname: { + type: 'string' + }, + os: { + type: 'string' + }, + arch: { + type: 'string' + }, + agentVersion: { + type: 'string' + }, + remoteIp: { + type: 'string' + }, + // unknown-host, known-host-no-agent, rebind, identity-conflict, reissue, no-mac + reason: { + type: 'string' + }, + // pending, issued or denied + state: { + type: 'string', + defaultsTo: 'pending' + }, + // The issued leaf and chain, kept only until the agent collects them. + cert: { + type: 'string', + defaultsTo: '' + }, + // ms + decidedAt: { + type: 'number' + }, + // The admin's user name, '' on an automatic path. + decidedBy: { + type: 'string' + }, + // token, deploy or admin + decidedVia: { + type: 'string' + } + } +}; diff --git a/api/models/Host.js b/api/models/Host.js index f14c741..2bcf0f1 100644 --- a/api/models/Host.js +++ b/api/models/Host.js @@ -99,13 +99,23 @@ function normalizeIdentity(values) { }); } +// The host name rule. api/helpers/agent/create-pending-host.js checks an agent's +// hostname against it, so it lives in one place (Host.nameRegex). +const NAME_REGEX = /^[a-z\d]([a-z\d\-]{0,61}[a-z\d])?(\.[a-z\d]([a-z\d\-]{0,61}[a-z\d])?)*$/i; + +// The fields that only the fog-agent enroll code writes (a forged +// agentFingerprint would bind a key to a host). The edit page does not show +// them, and general/save, create and update drop them from a request body. +// Exposed as Host.serverOwned. +const SERVER_OWNED = ['agentFingerprint', 'agentNotAfter', 'agentVersion', 'agentCheckin', 'agentId']; + module.exports = { attributes: { name: { type: 'string', required: true, maxLength: 63, - regex: /^[a-z\d]([a-z\d\-]{0,61}[a-z\d])?(\.[a-z\d]([a-z\d\-]{0,61}[a-z\d])?)*$/i, + regex: NAME_REGEX, unique: true }, description: { @@ -204,6 +214,28 @@ module.exports = { type: 'boolean', defaultsTo: false }, + // --- fog-agent enrollment (api/helpers/agent/issue.js): server-owned, see + // SERVER_OWNED above. agentNotAfter is UTC "YYYY-MM-DD HH:MM:SS"; the + // checkin is ms. agentId is the host number in the agent certificate + // (CN=fog-agent host ), assigned once and never reused. It is + // 0 until the host first gets an agent, so its unique index is partial + // (api/helpers/agent/ensure-indexes.js). --- + agentFingerprint: { + type: 'string' + }, + agentNotAfter: { + type: 'string' + }, + agentVersion: { + type: 'string' + }, + agentCheckin: { + type: 'number' + }, + agentId: { + type: 'number', + isInteger: true + }, image: { model: 'image' }, @@ -224,5 +256,8 @@ module.exports = { beforeCreate: beforeSave, beforeUpdate: beforeSave, // A custom model method (sails.models.host.normalizeGroups). - normalizeGroups + normalizeGroups, + // Custom model values: the host name rule and the server-owned agent fields. + nameRegex: NAME_REGEX, + serverOwned: SERVER_OWNED }; diff --git a/config/bootstrap.js b/config/bootstrap.js index b9d652b..e31b694 100644 --- a/config/bootstrap.js +++ b/config/bootstrap.js @@ -20,6 +20,10 @@ module.exports.bootstrap = async function() { // no index, and createIndex does nothing when it exists. await sails.helpers.group.ensureIndex(); + // The fog-agent enrollment indexes (the unique fingerprint, token hash and + // agentId), for the same reason. + await sails.helpers.agent.ensureIndexes(); + // By convention, this is a good place to set up fake data during development. // // For example: diff --git a/config/policies.js b/config/policies.js index 29d6571..52777a3 100644 --- a/config/policies.js +++ b/config/policies.js @@ -31,6 +31,14 @@ module.exports.policies = { // Group name list (checks host read permission itself -- no :model param here) 'host/groups': ['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'], + 'agent/decide': ['isLoggedIn','isAuthenticated','apiCsrfGuard'], + 'agent/tokens': ['isLoggedIn','isAuthenticated','apiCsrfGuard'], + 'agent/mint-token': ['isLoggedIn','isAuthenticated','apiCsrfGuard'], + 'agent/revoke-token': ['isLoggedIn','isAuthenticated','apiCsrfGuard'], + // Image Policies 'image/capture': ['isLoggedIn','isAuthenticated', 'image/capture'], 'image/deploy': ['isLoggedIn','isAuthenticated', 'image/deploy'], @@ -77,6 +85,9 @@ module.exports.policies = { // The CA files are public: the agent fetches them before it has a session 'agent/ca-file': true, + // So is the enroll route: the agent has no session (it proves its key by the CSR) + 'agent/enroll': true, + // System info 'system/info': true, 'system/bandwidth': true, diff --git a/config/routes.js b/config/routes.js index 7da4cf2..a21f320 100644 --- a/config/routes.js +++ b/config/routes.js @@ -63,6 +63,14 @@ module.exports.routes = { 'POST /api/v1/host/bulk': {action: 'host/bulk', csrf: false}, 'GET /api/v1/host/groups': {action: 'host/groups', 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}, + 'POST /api/v1/agent/enrollment/:id/:action': {action: 'agent/decide', csrf: false}, + 'GET /api/v1/agent/tokens': {action: 'agent/tokens', csrf: false}, + 'POST /api/v1/agent/token': {action: 'agent/mint-token', csrf: false}, + 'DELETE /api/v1/agent/token/:id': {action: 'agent/revoke-token', csrf: false}, + // Global search (must precede the :model routes). 'GET /api/v1/search': {action: 'search', csrf: false}, @@ -99,6 +107,10 @@ module.exports.routes = { 'GET /management/other/ca.cert.der': {action: 'agent/ca-file', file: 'root.der'}, 'GET /management/other/agent-ca-bundle.pem': {action: 'agent/ca-file', file: 'agent-ca-bundle.pem'}, + // fog-agent enrollment (public, no session: the agent has no certificate yet). + // Agent-facing, so it follows the FOG 1.6 wire format, not fog-node's API. + 'POST /agent/v1/enroll': {action: 'agent/enroll', csrf: false}, + // Host Views 'GET /hosts': {action: 'pages/list/hosts'}, 'GET /hosts/create': {action: 'pages/create/hosts'}, diff --git a/eslint.config.js b/eslint.config.js index b83715b..fce8dbe 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -38,9 +38,14 @@ const rules = { // tx_/rx_ set mirrors the field names the `systeminformation` package hands // us. Renaming them would change a public API response for cosmetic reasons. // grants_list is a group list row field, named as in FOG 1.6 - // (fog.group.list.js). Purely internal snake_case locals are still reported. + // (fog.group.list.js). The fog-agent enroll wire format is FOG 1.6's and the + // same agent binary speaks it to both servers, so its JSON keys keep their + // names (api/controllers/agent/enroll.js). Purely internal snake_case locals + // are still reported. 'camelcase': ['warn', {'properties':'always', 'allow': [ - '^default_iface$', '^(tx|rx)_(bytes|errors|dropped|sec)$', '^grants_list$' + '^default_iface$', '^(tx|rx)_(bytes|errors|dropped|sec)$', '^grants_list$', + '^(retry_after|host_id|certificate_pem|not_after|csr_pem|agent_version)$', + '^(system_uuid|system_serial|board_serial|chassis_asset|smbios_version)$' ]}], 'comma-style': ['warn', 'last'], // 'multi-line' rather than the template's default 'all'. Every one of the diff --git a/test/integration/agent-admin.test.js b/test/integration/agent-admin.test.js new file mode 100644 index 0000000..dd08663 --- /dev/null +++ b/test/integration/agent-admin.test.js @@ -0,0 +1,358 @@ +const assert = require('assert'); +const crypto = require('crypto'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); +const supertest = require('supertest'); +const agentCsr = require('../support/agent-csr'); +const support = require('../support/pki'); + +// The fog-agent admin JSON routes (contract 6.2): the pending enrollments, the +// approve and deny decision, and the enrollment tokens. They follow fog-node's +// conventions (camelCase, ms timestamps, errors as {error}), and each action +// checks its host permission: read, update, create, destroy. +describe('Agent admin::', 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 = 'mca' + RUN; + let seq = 0; + const uniq = () => PREFIX + (seq++); + const mac = () => '02:' + crypto.randomBytes(5).toString('hex').match(/../g).join(':'); + const bare = (m) => m.replace(/[:-]/g, ''); + + const Enrollment = () => sails.models.agentenrollment; + const Token = () => sails.models.agentenrolltoken; + const fingerprints = []; + + async function newCsr() { + const c = await agentCsr.newCsr(); + fingerprints.push(c.fingerprint); + return c; + } + const body = (c, macs, extra = {}) => Object.assign({ + protocol: 1, + agent_version: '1.0.0', + os: 'linux', + arch: 'amd64', + hostname: '', + identity: {system_uuid: '', system_serial: '', board_serial: '', chassis_asset: '', macs}, + csr_pem: c.pem + }, extra); + const enroll = (b) => supertest(app()).post('/agent/v1/enroll').send(b); + const rowOf = (c) => Enrollment().findOne({fingerprint: c.fingerprint}); + + // Signs in as a browser does (see group-membership.test.js). + async function signIn(username, password) { + const agent = supertest.agent(app()); + let res = await agent.get('/csrfToken').expect(200); + await agent.post('/login').type('form').set(...HTML) + .send({username, password, _csrf: res.body._csrf}) + .expect(302).expect('Location', '/'); + res = await agent.get('/csrfToken').expect(200); + return {agent, csrf: res.body._csrf}; + } + // A non-admin user whose role holds the given stock.host permissions. + async function limited(label, host) { + const name = `${PREFIX}-${label}`; + const role = await sails.models.role.create({name, isAdmin: false, permissions: {stock: {host}}}).fetch(); + await sails.models.user.create({username: name, password: 'mocha-agent-pw', email: `${name}@example.com`, roles: [role.id]}); + return signIn(name, 'mocha-agent-pw'); + } + + async function cleanup() { + const rows = await Enrollment().find({fingerprint: fingerprints}); + await sails.models.host.destroy({id: rows.map((r) => r.host).filter(Boolean)}); + await sails.models.host.destroy({name: {startsWith: PREFIX}}); + await Enrollment().destroy({fingerprint: fingerprints}); + await Token().destroy({name: {startsWith: PREFIX}}); + await sails.models.user.destroy({username: {startsWith: PREFIX}}); + await sails.models.role.destroy({name: {startsWith: PREFIX}}); + } + + let admin; + before(async () => { + await cleanup(); + admin = await signIn('mochatestadmin', 'mochatestadmin'); + }); + after(cleanup); + + // A known host that has no agent, and a pending request for it. + async function pendingFor(extra = {}) { + const m = mac(); + const host = await sails.models.host.create({name: uniq(), macs: [bare(m)], pending: false}).fetch(); + const c = await newCsr(); + await enroll(body(c, [m], extra)).expect(202); + return {host, c, m, row: await rowOf(c)}; + } + + describe('GET /api/v1/agent/enrollments', () => { + it('lists the pending rows oldest first, with the admin fields and never the csr or cert', async () => { + const first = await pendingFor({hostname: 'one'}); + const second = await pendingFor({hostname: 'two'}); + const done = await pendingFor(); + await Enrollment().updateOne({id: done.row.id}).set({state: 'denied'}); + + const res = await admin.agent.get('/api/v1/agent/enrollments').set(...AJAX).expect(200); + assert.deepStrictEqual(Object.keys(res.body), ['data']); + const ids = res.body.data.map((r) => r.id); + assert.ok(ids.indexOf(first.row.id) >= 0 && ids.indexOf(first.row.id) < ids.indexOf(second.row.id), 'oldest first'); + assert.ok(!ids.includes(done.row.id), 'a denied row is not pending'); + const entry = res.body.data.find((r) => r.id === first.row.id); + assert.deepStrictEqual(Object.keys(entry).sort(), [ + 'agentVersion', 'arch', 'createdAt', 'fingerprint', 'hostID', 'hostname', 'id', 'identity', 'os', 'reason', 'remoteIp', 'updatedAt' + ]); + assert.strictEqual(entry.hostID, first.host.id); + assert.strictEqual(entry.hostname, 'one'); + assert.strictEqual(entry.reason, 'known-host-no-agent'); + assert.strictEqual(entry.fingerprint, first.c.fingerprint); + assert.deepStrictEqual(entry.identity.macs, [first.m]); + assert.strictEqual(typeof entry.createdAt, 'number'); + assert.strictEqual(typeof entry.updatedAt, 'number'); + assert.ok(!JSON.stringify(res.body).includes('BEGIN CERTIFICATE REQUEST')); + }); + + it('answers 403 without host.read', async () => { + const none = await limited('enr-none', {update: true, create: true, destroy: true}); + await none.agent.get('/api/v1/agent/enrollments').set(...AJAX).expect(403); + }); + + it('answers 403 to a request with no session', async () => { + await supertest(app()).get('/api/v1/agent/enrollments').set('Accept', 'application/json').expect(403); + }); + }); + + describe('POST /api/v1/agent/enrollment/:id/:action', () => { + const decide = (who, id, action, headers = [AJAX]) => { + let req = who.agent.post(`/api/v1/agent/enrollment/${id}/${action}`); + for (const h of headers) { req = req.set(...h); } + return req; + }; + + it('approve: issues, stores the certificate for the agent, and the agent collects it once', async () => { + const {host, c, m, row} = await pendingFor(); + const res = await decide(admin, row.id, 'approve').expect(200); + assert.deepStrictEqual(res.body, {id: row.id, hostID: host.id, state: 'issued'}); + + const issued = await rowOf(c); + assert.deepStrictEqual([issued.state, issued.decidedVia, issued.decidedBy], ['issued', 'admin', 'mochatestadmin']); + assert.ok(issued.cert.startsWith('-----BEGIN CERTIFICATE-----')); + assert.ok(issued.decidedAt > 0); + const bound = await sails.models.host.findOne({id: host.id}); + assert.strictEqual(bound.agentFingerprint, c.fingerprint); + assert.strictEqual(bound.pending, false); + assert.ok(bound.agentId > 0); + + // It is not pending any more. + const list = await admin.agent.get('/api/v1/agent/enrollments').set(...AJAX).expect(200); + assert.ok(!list.body.data.some((r) => r.id === row.id)); + + // The agent's next request: 200, once, with the leaf for this host and key. + const got = await enroll(body(c, [m])).expect(200); + assert.strictEqual(got.body.host_id, bound.agentId); + assert.ok(Number.isInteger(got.body.host_id)); + const leaf = new crypto.X509Certificate(got.body.certificate_pem); + assert.ok(leaf.subject.split('\n').includes(`CN=fog-agent host ${bound.agentId}`)); + assert.strictEqual(sails.helpers.agent.keyFingerprint(got.body.certificate_pem), c.fingerprint); + assert.strictEqual((await rowOf(c)).cert, ''); + const reissue = await enroll(body(c, [m])).expect(202); + assert.strictEqual(reissue.body.reason, 'reissue'); + }); + + it('approve: also approves the pending host that an unknown machine created', async () => { + const c = await newCsr(); + const name = uniq(); + await enroll(body(c, [mac()], {hostname: name})).expect(202); + const row = await rowOf(c); + assert.strictEqual((await sails.models.host.findOne({id: row.host})).pending, true); + await decide(admin, row.id, 'approve').expect(200); + assert.strictEqual((await sails.models.host.findOne({id: row.host})).pending, false); + }); + + it('deny: the row is final, the agent gets 403, and a later approve is 409', async () => { + const {c, m, row} = await pendingFor(); + const res = await decide(admin, row.id, 'deny').expect(200); + assert.deepStrictEqual(res.body, {id: row.id, hostID: row.host, state: 'denied'}); + const denied = await rowOf(c); + assert.deepStrictEqual([denied.state, denied.cert, denied.decidedVia, denied.decidedBy], ['denied', '', 'admin', 'mochatestadmin']); + assert.ok(await sails.models.host.findOne({id: row.host}), 'the host stays'); + + const agent = await enroll(body(c, [m])).expect(403); + assert.deepStrictEqual(agent.body, {status: 'denied', reason: 'admin'}); + const again = await decide(admin, row.id, 'approve').expect(409); + assert.deepStrictEqual(again.body, {error: 'enrollment is not pending'}); + await decide(admin, row.id, 'deny').expect(409); + }); + + it('answers 409 for an issued row', async () => { + const {row} = await pendingFor(); + await decide(admin, row.id, 'approve').expect(200); + const res = await decide(admin, row.id, 'approve').expect(409); + assert.deepStrictEqual(res.body, {error: 'enrollment is not pending'}); + }); + + it('answers 409 for a row with no host (no-mac), and leaves it pending', async () => { + const c = await newCsr(); + await enroll(body(c, [])).expect(202); + const row = await rowOf(c); + assert.strictEqual(row.reason, 'no-mac'); + const res = await decide(admin, row.id, 'approve').expect(409); + assert.deepStrictEqual(res.body, {error: 'enrollment is not bound to a host'}); + assert.strictEqual((await rowOf(c)).state, 'pending'); + // Deny still works for it. + await decide(admin, row.id, 'deny').expect(200); + }); + + it('answers 404 for an unknown action and for no such enrollment', async () => { + const {row} = await pendingFor(); + assert.deepStrictEqual((await decide(admin, row.id, 'revoke').expect(404)).body, {error: 'unknown action'}); + assert.strictEqual((await rowOf({fingerprint: row.fingerprint})).state, 'pending'); + for (const id of ['5f0000000000000000000000', 'nonsense']) { + assert.deepStrictEqual((await decide(admin, id, 'approve').expect(404)).body, {error: 'no such enrollment'}, id); + } + }); + + it('answers 503 signing when the PKI is missing, and leaves the row pending', async () => { + const {c, row} = await pendingFor(); + const saved = sails.config.custom.pkiDir; + sails.config.custom.pkiDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fog-pki-empty-')); + try { + const res = await decide(admin, row.id, 'approve').expect(503); + assert.deepStrictEqual(res.body, {error: 'signing'}); + } finally { + fs.rmSync(sails.config.custom.pkiDir, {recursive: true, force: true}); + sails.config.custom.pkiDir = saved; + } + assert.strictEqual((await rowOf(c)).state, 'pending'); + await decide(admin, row.id, 'approve').expect(200); + }); + + it('answers 403 without host.update', async () => { + const {row} = await pendingFor(); + const readOnly = await limited('dec-ro', {read: true, create: true, destroy: true}); + await decide(readOnly, row.id, 'approve').expect(403); + await decide(readOnly, row.id, 'deny').expect(403); + assert.strictEqual((await Enrollment().findOne({id: row.id})).state, 'pending'); + }); + + it('answers 403 to a cookie mutation without the CSRF header', async () => { + const {row} = await pendingFor(); + await decide(admin, row.id, 'approve', []).expect(403); + assert.strictEqual((await Enrollment().findOne({id: row.id})).state, 'pending'); + }); + }); + + describe('tokens', () => { + const mint = (who, fields, headers = [AJAX]) => { + let req = who.agent.post('/api/v1/agent/token'); + for (const h of headers) { req = req.set(...h); } + return req.send(fields); + }; + const future = () => Date.now() + 3600000; + + it('mints a token: 48 hex characters, shown once, stored only as its sha256', async () => { + const expires = future(); + const res = await mint(admin, {name: ` ${uniq()} `, uses: 3, expires}).expect(200); + assert.deepStrictEqual(Object.keys(res.body).sort(), ['expires', 'id', 'name', 'token']); + assert.match(res.body.token, /^[0-9a-f]{48}$/); + assert.ok(res.body.name.startsWith(PREFIX) && res.body.name === res.body.name.trim()); + assert.strictEqual(res.body.expires, expires); + const row = await Token().findOne({id: res.body.id}); + assert.strictEqual(row.hash, crypto.createHash('sha256').update(res.body.token).digest('hex')); + assert.deepStrictEqual([row.uses, row.expires, row.createdBy], [3, expires, 'mochatestadmin']); + assert.ok(!JSON.stringify(row).includes(res.body.token)); + }); + + it('defaults uses to 1, accepts -1 and an ISO date', async () => { + const dflt = await mint(admin, {name: uniq(), expires: future()}).expect(200); + assert.strictEqual((await Token().findOne({id: dflt.body.id})).uses, 1); + const unlimited = await mint(admin, {name: uniq(), uses: -1, expires: new Date(future()).toISOString()}).expect(200); + const row = await Token().findOne({id: unlimited.body.id}); + assert.strictEqual(row.uses, -1); + assert.strictEqual(unlimited.body.expires, row.expires); + assert.ok(row.expires > Date.now()); + }); + + it('answers 400 {error} for a bad name, uses or expires, and stores nothing', async () => { + const before = await Token().count(); + const cases = [ + [{expires: future()}, /name/], + [{name: ' ', expires: future()}, /name/], + [{name: 'x'.repeat(192), expires: future()}, /name/], + [{name: uniq(), uses: 0, expires: future()}, /uses/], + [{name: uniq(), uses: -2, expires: future()}, /uses/], + [{name: uniq(), uses: 1.5, expires: future()}, /uses/], + [{name: uniq(), uses: 'many', expires: future()}, /uses/], + [{name: uniq()}, /expires/], + [{name: uniq(), expires: Date.now() - 1000}, /expires/], + [{name: uniq(), expires: 'next week'}, /expires/], + [{name: uniq(), expires: null}, /expires/] + ]; + for (const [fields, pattern] of cases) { + const res = await mint(admin, fields).expect(400); + assert.deepStrictEqual(Object.keys(res.body), ['error']); + assert.match(res.body.error, pattern, JSON.stringify(fields)); + } + assert.strictEqual(await Token().count(), before); + }); + + it('lists tokens with state spent, expired or active, and never the hash', async () => { + const active = (await mint(admin, {name: uniq(), expires: future()}).expect(200)).body; + const spent = await Token().create({name: uniq(), hash: crypto.randomBytes(32).toString('hex'), uses: 0, expires: future(), createdBy: 'x'}).fetch(); + const expired = await Token().create({name: uniq(), hash: crypto.randomBytes(32).toString('hex'), uses: 4, expires: Date.now() - 1000, createdBy: 'x'}).fetch(); + const res = await admin.agent.get('/api/v1/agent/tokens').set(...AJAX).expect(200); + assert.deepStrictEqual(Object.keys(res.body), ['data']); + const byId = (id) => res.body.data.find((t) => t.id === id); + assert.strictEqual(byId(active.id).state, 'active'); + assert.strictEqual(byId(spent.id).state, 'spent'); + assert.strictEqual(byId(expired.id).state, 'expired'); + assert.deepStrictEqual(Object.keys(byId(active.id)).sort(), ['createdAt', 'createdBy', 'expires', 'id', 'name', 'state', 'uses']); + assert.ok(!JSON.stringify(res.body).includes('"hash"')); + assert.ok(!JSON.stringify(res.body).includes(active.token)); + }); + + it('a minted token enrolls an agent at once', async () => { + const minted = (await mint(admin, {name: uniq(), expires: future()}).expect(200)).body; + const c = await newCsr(); + await enroll(body(c, [mac()], {token: minted.token})).expect(200); + const list = await admin.agent.get('/api/v1/agent/tokens').set(...AJAX).expect(200); + assert.strictEqual(list.body.data.find((t) => t.id === minted.id).state, 'spent'); + }); + + it('revokes a token: the row goes, and the token no longer works', async () => { + const minted = (await mint(admin, {name: uniq(), expires: future()}).expect(200)).body; + const res = await admin.agent.delete(`/api/v1/agent/token/${minted.id}`).set(...AJAX).expect(200); + assert.deepStrictEqual(res.body, {id: minted.id}); + assert.strictEqual(await Token().findOne({id: minted.id}), undefined); + const gone = await admin.agent.delete(`/api/v1/agent/token/${minted.id}`).set(...AJAX).expect(404); + assert.deepStrictEqual(gone.body, {error: 'no such token'}); + await admin.agent.delete('/api/v1/agent/token/nonsense').set(...AJAX).expect(404); + const res2 = await enroll(body(await newCsr(), [mac()], {token: minted.token})).expect(202); + assert.strictEqual(res2.body.status, 'pending'); + }); + + it('answers 403 without the host permission, for each route', async () => { + const minted = (await mint(admin, {name: uniq(), expires: future()}).expect(200)).body; + const noRead = await limited('tok-noread', {create: true, destroy: true, update: true}); + const noCreate = await limited('tok-nocreate', {read: true, destroy: true, update: true}); + const noDestroy = await limited('tok-nodestroy', {read: true, create: true, update: true}); + await noRead.agent.get('/api/v1/agent/tokens').set(...AJAX).expect(403); + await mint(noCreate, {name: uniq(), expires: future()}).expect(403); + await noDestroy.agent.delete(`/api/v1/agent/token/${minted.id}`).set(...AJAX).expect(403); + assert.ok(await Token().findOne({id: minted.id})); + }); + + it('answers 403 to a cookie mutation without the CSRF header', async () => { + const before = await Token().count(); + await mint(admin, {name: uniq(), expires: future()}, []).expect(403); + assert.strictEqual(await Token().count(), before); + const minted = (await mint(admin, {name: uniq(), expires: future()}).expect(200)).body; + await admin.agent.delete(`/api/v1/agent/token/${minted.id}`).expect(403); + assert.ok(await Token().findOne({id: minted.id})); + }); + }); +}); diff --git a/test/integration/agent-enroll.test.js b/test/integration/agent-enroll.test.js new file mode 100644 index 0000000..38e0da4 --- /dev/null +++ b/test/integration/agent-enroll.test.js @@ -0,0 +1,710 @@ +const assert = require('assert'); +const crypto = require('crypto'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); +const supertest = require('supertest'); +const {verifies} = require('../../api/lib/agent-pki'); +const agentCsr = require('../support/agent-csr'); +const support = require('../support/pki'); + +// POST /agent/v1/enroll: the fog-agent enrollment wire contract of FOG 1.6 +// (briefs/research/2026-11-10-agent-enroll-contract.md, sections 1.1, 2.1 and +// 3). The same agent binary must work against both servers, so the statuses, +// the JSON keys and the strings are asserted exactly. The CSRs are built as the +// agent builds them: ECDSA P-256 and an empty subject (contract 4.3). +describe('Agent enroll::', function () { + this.timeout(120000); + + const fixtureDir = support.useFixture(); + const app = () => sails.hooks.http.app; + const HTML = ['Accept', 'text/html']; + const AJAX = ['X-Requested-With', 'XMLHttpRequest']; + // Every name this file creates starts with PREFIX. A host name is at most 15 + // characters, so the prefix and the counter stay short. + const RUN = crypto.randomBytes(3).toString('hex'); + const PREFIX = 'mc' + RUN; + let seq = 0; + const uniq = () => PREFIX + (seq++); + // A locally administered MAC, in the colon form that the agent sends. + const mac = () => '02:' + crypto.randomBytes(5).toString('hex').match(/../g).join(':'); + const bare = (m) => m.replace(/[:-]/g, '').toLowerCase(); + + const Enrollment = () => sails.models.agentenrollment; + const Token = () => sails.models.agentenrolltoken; + const fingerprints = []; + + // A CSR the way the agent makes it, and the fingerprint of its key. Each + // fingerprint is recorded, so cleanup removes its row and host. + const newKey = agentCsr.newKey; + async function csrFor(keys) { + const c = await agentCsr.csrFor(keys); + if (!fingerprints.includes(c.fingerprint)) { fingerprints.push(c.fingerprint); } + return c; + } + const newCsr = async () => csrFor(await newKey()); + + // The request body of the agent (client.go:46-56). + const request = (c, extra = {}) => Object.assign({ + protocol: 1, + agent_version: 'v0.0.1', + os: 'linux', + arch: 'amd64', + hostname: '', + identity: {system_uuid: '', system_serial: '', board_serial: '', chassis_asset: '', macs: []}, + csr_pem: c.pem + }, extra); + const identity = (fields) => Object.assign({system_uuid: '', system_serial: '', board_serial: '', chassis_asset: '', macs: []}, fields); + const post = (body) => supertest(app()).post('/agent/v1/enroll').send(body); + const enroll = (c, extra) => post(request(c, extra)); + const rowOf = (c) => Enrollment().findOne({fingerprint: c.fingerprint}); + const keysOf = (body) => Object.keys(body).sort(); + + const mkHost = (fields = {}) => sails.models.host.create(Object.assign({name: uniq(), pending: false}, fields)).fetch(); + const hostOf = (id) => sails.models.host.findOne({id}); + + // A token with a known secret. + async function mkToken(fields = {}) { + const secret = crypto.randomBytes(24).toString('hex'); + const row = await Token().create(Object.assign({ + name: uniq(), uses: 1, expires: Date.now() + 3600000, createdBy: 'mocha', + hash: crypto.createHash('sha256').update(secret).digest('hex') + }, fields)).fetch(); + return {secret, row}; + } + const usesOf = async (token) => (await Token().findOne({id: token.row.id})).uses; + + // The Settings that a test touches are put back after it. + const settings = {}; + async function put(name, value) { + if (!(name in settings)) { settings[name] = await Setting.findOne({name}) || null; } + const updated = await Setting.updateOne({name}).set({value}); + if (!updated) { await Setting.create({name, description: 'mocha agent enroll', value}); } + } + async function restoreSettings() { + for (const [name, saved] of Object.entries(settings)) { + if (saved) { await Setting.updateOne({name}).set({value: saved.value}); } else { await Setting.destroy({name}); } + delete settings[name]; + } + } + + async function cleanup() { + const rows = await Enrollment().find({fingerprint: fingerprints}); + await sails.models.host.destroy({id: rows.map((r) => r.host).filter(Boolean)}); + await sails.models.host.destroy({name: {startsWith: PREFIX}}); + await Enrollment().destroy({fingerprint: fingerprints}); + await Token().destroy({name: {startsWith: PREFIX}}); + await restoreSettings(); + } + before(cleanup); + afterEach(restoreSettings); + after(cleanup); + + describe('the answers', () => { + it('answers 426 unsupported for a protocol other than 1, and for no JSON body', async () => { + const c = await newCsr(); + for (const protocol of [0, 2, undefined]) { + const res = await enroll(c, {protocol}).expect(426); + assert.deepStrictEqual(res.body, {status: 'unsupported', reason: 'protocol'}); + } + assert.deepStrictEqual((await supertest(app()).post('/agent/v1/enroll').expect(426)).body, {status: 'unsupported', reason: 'protocol'}); + assert.deepStrictEqual((await supertest(app()).post('/agent/v1/enroll').type('form').send('protocol=1').expect(400)).body, {status: 'error', reason: 'csr'}); + }); + + it('answers 400 csr for a CSR that is missing, garbage, or has a bad signature', async () => { + const good = await newCsr(); + const forged = agentCsr.forge(good.pem); + for (const csr_pem of [undefined, '', 'garbage', '-----BEGIN CERTIFICATE REQUEST-----\nAAAA\n-----END CERTIFICATE REQUEST-----\n', forged]) { + const res = await post(request(good, {csr_pem})).expect(400); + assert.deepStrictEqual(res.body, {status: 'error', reason: 'csr'}); + } + // The forged request left no row behind. + assert.strictEqual(await Enrollment().count({fingerprint: good.fingerprint}), 0); + }); + + it('answers 400 csr for a csr_pem over 16384 characters, before it is parsed', async () => { + const good = await newCsr(); + const res = await post(request(good, {csr_pem: good.pem + ' '.repeat(16384)})).expect(400); + assert.deepStrictEqual(res.body, {status: 'error', reason: 'csr'}); + assert.strictEqual(await Enrollment().count({fingerprint: good.fingerprint}), 0); + }); + + it('stores only the contract identity keys, capped, and at most 32 MACs', async () => { + const c = await newCsr(); + const macs = Array.from({length: 40}, mac); + await enroll(c, {identity: { + system_uuid: 'u'.repeat(1000), system_serial: 's', board_serial: 'b', chassis_asset: 'a', + smbios_version: '3.2', warnings: ['w', 5, 'x'.repeat(1000)], _directoryIdentity: {required: true}, + extra: {deep: 'z'.repeat(40000)}, macs: [...macs, 'bad', 7] + }}).expect(202); + const stored = (await rowOf(c)).identity; + assert.deepStrictEqual(Object.keys(stored).sort(), + ['board_serial', 'chassis_asset', 'macs', 'smbios_version', 'system_serial', 'system_uuid', 'warnings']); + assert.strictEqual(stored.system_uuid.length, 256); + assert.deepStrictEqual(stored.macs, macs.slice(0, 32)); + assert.deepStrictEqual([stored.warnings.length, stored.warnings[0], stored.warnings[1].length], [2, 'w', 256]); + assert.strictEqual(JSON.stringify(stored).includes('zzzz'), false); + }); + + it('hashes a token as the sha256 of its trimmed text', () => { + const hash = (s) => crypto.createHash('sha256').update(s).digest('hex'); + assert.strictEqual(sails.models.agentenrolltoken.hashOf(' \nabc\t'), hash('abc')); + }); + + it('answers 202 pending with the reason and retry_after 300', async () => { + const c = await newCsr(); + const res = await enroll(c, {identity: identity({macs: [mac()]})}).expect(202); + assert.deepStrictEqual(keysOf(res.body), ['reason', 'retry_after', 'status']); + assert.deepStrictEqual(res.body, {status: 'pending', reason: 'unknown-host', retry_after: 300}); + }); + + it('accepts the CSR for the same key as one row, whatever its encoding', async () => { + const keys = await newKey(); + const first = await csrFor(keys); + const second = await csrFor(keys); + assert.notStrictEqual(first.pem, second.pem, 'ECDSA signatures differ'); + assert.strictEqual(first.fingerprint, second.fingerprint); + }); + }); + + describe('the reasons', () => { + it('unknown-host with a MAC: creates one pending host named by the request hostname', async () => { + const c = await newCsr(); + const m = mac(); + const name = uniq(); + const res = await enroll(c, {hostname: name, identity: identity({macs: [m], system_serial: `MOCHA-${name}`, system_uuid: crypto.randomUUID()})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host'); + const row = await rowOf(c); + const host = await hostOf(row.host); + assert.strictEqual(host.name, name); + assert.strictEqual(host.pending, true); + assert.strictEqual(host.description, 'Pending Registration created by FOG_AGENT'); + assert.deepStrictEqual(host.macs, [bare(m)]); + assert.strictEqual(host.serial, `mocha-${name}`); + assert.strictEqual(row.state, 'pending'); + assert.strictEqual(row.cert, ''); + assert.strictEqual(row.agentVersion, '0.0.1', 'the leading v is stripped'); + assert.strictEqual(await sails.models.host.count({name: {startsWith: name}}), 1); + }); + + it('unknown-host: a hostname that fails the name rule or is over 15 characters becomes agent-', async () => { + for (const hostname of ['bad name!', 'x'.repeat(16), '']) { + const c = await newCsr(); + await enroll(c, {hostname, identity: identity({macs: [mac()]})}).expect(202); + const host = await hostOf((await rowOf(c)).host); + assert.strictEqual(host.name, 'agent-' + c.fingerprint.slice(0, 8), `hostname ${JSON.stringify(hostname)}`); + } + }); + + it('unknown-host: a second key with the same MAC gets its own pending host with a -1 name', async () => { + const m = mac(); + const name = uniq(); + const names = []; + for (const unused of [1, 2, 3]) { + const c = await newCsr(); + const res = await enroll(c, {hostname: name, identity: identity({macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host', 'the resolver skips pending hosts'); + names.push((await hostOf((await rowOf(c)).host)).name); + } + assert.deepStrictEqual(names, [name, name + '-1', name + '-2']); + }); + + it('unknown-host: the -1 suffix cuts a 15 character base so the name stays at 15', async () => { + const m = mac(); + const name = PREFIX + 'abcdefghi'.slice(0, 15 - PREFIX.length); + assert.strictEqual(name.length, 15); + const names = []; + for (const unused of [1, 2]) { + const c = await newCsr(); + await enroll(c, {hostname: name, identity: identity({macs: [m]})}).expect(202); + names.push((await hostOf((await rowOf(c)).host)).name); + } + assert.deepStrictEqual(names, [name, name.slice(0, 13) + '-1']); + }); + + it('no-mac: creates no host, and 202 says no-mac', async () => { + const c = await newCsr(); + const before = await sails.models.host.count(); + const res = await enroll(c, {hostname: uniq(), identity: identity({macs: ['not a mac', 'aa:bb:cc']})}).expect(202); + assert.deepStrictEqual(res.body, {status: 'pending', reason: 'no-mac', retry_after: 300}); + assert.strictEqual(await sails.models.host.count(), before); + assert.strictEqual((await rowOf(c)).host, ''); + }); + + it('no-mac never auto-approves, even with a valid token', async () => { + const token = await mkToken(); + const c = await newCsr(); + const res = await enroll(c, {token: token.secret}).expect(202); + assert.strictEqual(res.body.reason, 'no-mac'); + assert.strictEqual(await usesOf(token), 1); + }); + + it('stores only the valid MACs, in the host form, without repeats', async () => { + const c = await newCsr(); + const m = mac(); + const other = mac(); + await enroll(c, {identity: identity({macs: [m.toUpperCase(), m.replace(/:/g, '-'), 'zz:zz:zz:zz:zz:zz', 'aabbccddeeff', 42, other]})}).expect(202); + const host = await hostOf((await rowOf(c)).host); + assert.deepStrictEqual(host.macs, [bare(m), bare(other)]); + }); + + it('known-host-no-agent: a MAC matches a host without an agent', async () => { + const m = mac(); + const host = await mkHost({macs: [bare(m)]}); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'known-host-no-agent'); + assert.strictEqual((await rowOf(c)).host, host.id); + assert.strictEqual((await hostOf(host.id)).pending, false, 'a known host is not changed'); + }); + + it('known-host-no-agent: the SMBIOS serial and uuid match, without case', async () => { + const serial = `MOCHA-${uniq()}`; + const guid = crypto.randomUUID(); + const host = await mkHost({serial, guid}); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({system_serial: ` ${serial.toUpperCase()} `, system_uuid: guid.toUpperCase()})}).expect(202); + assert.strictEqual(res.body.reason, 'known-host-no-agent'); + assert.strictEqual((await rowOf(c)).host, host.id); + }); + + it('the asset tag scores only next to a firmware match', async () => { + const asset = `ASSET-${uniq()}`; + await mkHost({asset}); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({chassis_asset: asset, macs: [mac()]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host', 'an asset alone matches nothing'); + }); + + it('SMBIOS: a placeholder, a repeated character and an empty value match nothing', async () => { + const shared = ['To be filled by O.E.M.', '0000000000', 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF', 'N/A']; + for (const value of shared) { + await mkHost({serial: value}); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({system_serial: value, macs: [mac()]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host', value); + } + }); + + it('SMBIOS: a tie between two hosts is no match', async () => { + const serial = `MOCHA-${uniq()}`; + await mkHost({serial}); + await mkHost({serial}); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({system_serial: serial, macs: [mac()]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host'); + }); + + it('SMBIOS: more matching fields win over fewer', async () => { + const serial = `MOCHA-${uniq()}`; + const guid = crypto.randomUUID(); + await mkHost({serial}); + const best = await mkHost({serial, guid}); + const c = await newCsr(); + await enroll(c, {identity: identity({system_serial: serial, system_uuid: guid})}).expect(202); + assert.strictEqual((await rowOf(c)).host, best.id); + }); + + it('the Setting FOG_HOST_IDENTIFY_SMBIOS off makes the match by MAC only', async () => { + const serial = `MOCHA-${uniq()}`; + const bySerial = await mkHost({serial}); + const m = mac(); + const byMac = await mkHost({macs: [bare(m)]}); + await put('FOG_HOST_IDENTIFY_SMBIOS', 'off'); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({system_serial: serial, macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'known-host-no-agent'); + assert.strictEqual((await rowOf(c)).host, byMac.id); + assert.notStrictEqual(byMac.id, bySerial.id); + }); + + it('MAC: with several hosts, the one with the most matching MACs wins, and a tie is no match', async () => { + const [a, b] = [mac(), mac()]; + await mkHost({macs: [bare(a)]}); + const both = await mkHost({macs: [bare(a), bare(b)]}); + const c = await newCsr(); + await enroll(c, {identity: identity({macs: [a, b]})}).expect(202); + assert.strictEqual((await rowOf(c)).host, both.id); + + const [x, y] = [mac(), mac()]; + await mkHost({macs: [bare(x)]}); + await mkHost({macs: [bare(y)]}); + const tie = await newCsr(); + const res = await enroll(tie, {identity: identity({macs: [x, y]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host'); + }); + + it('a pending host never resolves', async () => { + const m = mac(); + await mkHost({macs: [bare(m)], pending: true}); + const res = await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host'); + }); + + it('rebind: the resolved host already has an agent key', async () => { + const m = mac(); + await mkHost({macs: [bare(m)], agentFingerprint: crypto.randomBytes(32).toString('hex')}); + const res = await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'rebind'); + }); + + it('identity-conflict: firmware and MAC name different hosts, and the firmware host is kept', async () => { + const serial = `MOCHA-${uniq()}`; + const m = mac(); + const byFirmware = await mkHost({serial}); + await mkHost({macs: [bare(m)]}); + const c = await newCsr(); + const res = await enroll(c, {identity: identity({system_serial: serial, macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'identity-conflict'); + assert.strictEqual((await rowOf(c)).host, byFirmware.id); + }); + }); + + describe('a repeat with the same key', () => { + it('answers from the row: pending stays 202 with the same reason, and never re-resolves the host', async () => { + const c = await newCsr(); + const m = mac(); + const name = uniq(); + const first = await enroll(c, {hostname: name, identity: identity({macs: [m]})}).expect(202); + const row1 = await rowOf(c); + // A host that would now match. The repeat must not look for it. + await mkHost({macs: [bare(m)]}); + const second = await enroll(c, {agent_version: 'V9.9', os: 'windows', hostname: 'renamed', identity: identity({macs: [m]})}).expect(202); + assert.deepStrictEqual(second.body, first.body); + const row2 = await rowOf(c); + assert.strictEqual(row2.reason, 'unknown-host'); + assert.strictEqual(row2.host, row1.host); + assert.strictEqual(row2.csr, row1.csr, 'the first CSR is the one kept'); + assert.deepStrictEqual([row2.agentVersion, row2.os, row2.hostname], ['9.9', 'windows', 'renamed']); + // The repeat created no second pending host for this machine. + assert.strictEqual(await sails.models.host.count({name: {startsWith: name}}), 1); + }); + + it('signs the first CSR, not the latest, and checks the later CSR for the same key', async () => { + const keys = await newKey(); + const first = await csrFor(keys); + const m = mac(); + await mkHost({macs: [bare(m)]}); + await enroll(first, {identity: identity({macs: [m]})}).expect(202); + const later = await csrFor(keys); + // A later CSR that fails the signature check is still 400. + await post(request(later, {csr_pem: agentCsr.forge(later.pem)})).expect(400); + assert.strictEqual((await rowOf(first)).csr, first.pem); + }); + + it('approved: 200 once with the certificate, then 202 reissue', async () => { + const m = mac(); + const host = await mkHost({macs: [bare(m)]}); + const c = await newCsr(); + await enroll(c, {identity: identity({macs: [m]})}).expect(202); + const row = await rowOf(c); + await sails.helpers.agent.issue.with({row, via: 'admin', by: 'mocha-admin', keepCert: true}); + + const issued = await enroll(c, {identity: identity({macs: [m]})}).expect(200); + assert.deepStrictEqual(keysOf(issued.body), ['certificate_pem', 'host_id', 'not_after', 'status']); + assert.strictEqual(issued.body.status, 'issued'); + assert.ok(Number.isInteger(issued.body.host_id), 'host_id is a JSON integer'); + assert.match(issued.body.not_after, /^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d$/); + const after = await hostOf(host.id); + assert.strictEqual(issued.body.host_id, after.agentId); + assert.strictEqual(after.agentNotAfter, issued.body.not_after); + assert.strictEqual(after.agentFingerprint, c.fingerprint); + assert.strictEqual(after.pending, false); + assert.strictEqual(after.agentVersion, '0.0.1'); + assert.ok(after.agentCheckin > 0); + + // The leaf: the server's subject, the agent's key, then the agent CA. + const pems = issued.body.certificate_pem.match(/-----BEGIN CERTIFICATE-----[^-]+-----END CERTIFICATE-----\n?/g); + assert.strictEqual(pems.length, 2, 'the leaf, then the agent CA only'); + const leaf = new crypto.X509Certificate(pems[0]); + assert.ok(leaf.subject.split('\n').includes(`CN=fog-agent host ${after.agentId}`)); + assert.strictEqual(sails.helpers.agent.keyFingerprint(pems[0]), c.fingerprint); + assert.ok(verifies(pems[0], pems[1], true)); + assert.strictEqual(pems[1], fs.readFileSync(path.join(fixtureDir(), 'agent-ca.pem'), 'utf8')); + + const doneRow = await rowOf(c); + assert.deepStrictEqual([doneRow.state, doneRow.cert, doneRow.decidedBy, doneRow.decidedVia], ['issued', '', 'mocha-admin', 'admin']); + + const again = await enroll(c, {identity: identity({macs: [m]})}).expect(202); + assert.deepStrictEqual(again.body, {status: 'pending', reason: 'reissue', retry_after: 300}); + assert.strictEqual((await rowOf(c)).state, 'pending'); + }); + + it('approved, then the host is deleted: the next request still gets 200 once, from the row and the stored leaf', async () => { + const m = mac(); + const host = await mkHost({macs: [bare(m)]}); + const c = await newCsr(); + await enroll(c, {identity: identity({macs: [m]})}).expect(202); + await sails.helpers.agent.issue.with({row: await rowOf(c), via: 'admin', by: 'mocha-admin', keepCert: true}); + const agentId = (await hostOf(host.id)).agentId; + const notAfter = (await hostOf(host.id)).agentNotAfter; + await sails.models.host.destroy({id: host.id}); + + const res = await enroll(c, {identity: identity({macs: [m]})}).expect(200); + assert.deepStrictEqual(keysOf(res.body), ['certificate_pem', 'host_id', 'not_after', 'status']); + assert.strictEqual(res.body.host_id, agentId, 'host_id comes from CN=fog-agent host in the leaf'); + assert.strictEqual(res.body.not_after, notAfter, 'not_after comes from the leaf'); + assert.strictEqual(sails.helpers.agent.keyFingerprint(res.body.certificate_pem), c.fingerprint); + assert.strictEqual((await rowOf(c)).cert, ''); + const next = await enroll(c, {identity: identity({macs: [m]})}).expect(202); + assert.strictEqual(next.body.reason, 'reissue'); + }); + + it('denied: 403 every time, and only the row details refresh', async () => { + const c = await newCsr(); + await enroll(c, {identity: identity({macs: [mac()]})}).expect(202); + const row = await rowOf(c); + await Enrollment().updateOne({id: row.id}).set({state: 'denied', decidedVia: 'admin'}); + for (const unused of [1, 2]) { + const res = await enroll(c, {agent_version: '2.0'}).expect(403); + assert.deepStrictEqual(res.body, {status: 'denied', reason: 'admin'}); + } + assert.strictEqual((await rowOf(c)).agentVersion, '2.0'); + assert.strictEqual((await rowOf(c)).state, 'denied'); + }); + }); + + describe('the host number', () => { + it('gives each host its own number, and a host keeps its number for a new key', async () => { + const [m1, m2] = [mac(), mac()]; + const h1 = await mkHost({macs: [bare(m1)]}); + const h2 = await mkHost({macs: [bare(m2)]}); + const ids = []; + for (const [h, m] of [[h1, m1], [h2, m2], [h1, m1]]) { + const c = await newCsr(); + await enroll(c, {identity: identity({macs: [m]})}).expect(202); + await sails.helpers.agent.issue.with({row: await rowOf(c), via: 'admin', by: 'mocha', keepCert: true}); + ids.push((await enroll(c, {identity: identity({macs: [m]})}).expect(200)).body.host_id); + assert.strictEqual((await hostOf(h.id)).agentId, ids[ids.length - 1]); + } + assert.ok(ids[0] > 0 && ids[1] > 0); + assert.notStrictEqual(ids[0], ids[1]); + assert.strictEqual(ids[2], ids[0], 'the second key of h1 is a rebind and keeps the number'); + }); + }); + + describe('a token', () => { + it('issues in the same request and spends one use', async () => { + const token = await mkToken({uses: 2}); + const m = mac(); + const c = await newCsr(); + const res = await enroll(c, {token: ` ${token.secret}\n`, hostname: uniq(), identity: identity({macs: [m]})}).expect(200); + assert.strictEqual(res.body.status, 'issued'); + assert.ok(Number.isInteger(res.body.host_id)); + assert.strictEqual(await usesOf(token), 1); + const row = await rowOf(c); + assert.deepStrictEqual([row.state, row.cert, row.decidedVia, row.decidedBy], ['issued', '', 'token', '']); + const host = await hostOf(row.host); + assert.strictEqual(host.pending, false, 'a pending host is approved with its agent'); + assert.strictEqual(host.agentFingerprint, c.fingerprint); + }); + + it('works for a repeat of a pending key', async () => { + const c = await newCsr(); + const m = mac(); + await enroll(c, {hostname: uniq(), identity: identity({macs: [m]})}).expect(202); + const token = await mkToken(); + await enroll(c, {token: token.secret, identity: identity({macs: [m]})}).expect(200); + assert.strictEqual(await usesOf(token), 0); + }); + + it('with uses -1 never spends', async () => { + const token = await mkToken({uses: -1}); + for (const unused of [1, 2]) { + await enroll(await newCsr(), {token: token.secret, identity: identity({macs: [mac()]})}).expect(200); + } + assert.strictEqual(await usesOf(token), -1); + }); + + it('an expired, spent or unknown token waits', async () => { + const expired = await mkToken({expires: Date.now() - 1000}); + const spent = await mkToken({uses: 0}); + const expiredUnlimited = await mkToken({uses: -1, expires: Date.now() - 1000}); + for (const secret of [expired.secret, spent.secret, expiredUnlimited.secret, crypto.randomBytes(24).toString('hex'), ' ']) { + const res = await enroll(await newCsr(), {token: secret, identity: identity({macs: [mac()]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host'); + } + assert.strictEqual(await usesOf(expired), 1); + assert.strictEqual(await usesOf(spent), 0); + }); + + it('a sign failure answers 503 signing, leaves the row pending, and spends nothing', async () => { + const token = await mkToken(); + const saved = sails.config.custom.pkiDir; + sails.config.custom.pkiDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fog-pki-empty-')); + const c = await newCsr(); + try { + const res = await enroll(c, {token: token.secret, identity: identity({macs: [mac()]})}).expect(503); + assert.deepStrictEqual(res.body, {status: 'error', reason: 'signing'}); + } finally { + fs.rmSync(sails.config.custom.pkiDir, {recursive: true, force: true}); + sails.config.custom.pkiDir = saved; + } + assert.strictEqual(await usesOf(token), 1); + assert.strictEqual((await rowOf(c)).state, 'pending'); + // With the PKI back, the same request issues. + await enroll(c, {token: token.secret, identity: identity({macs: [mac()]})}).expect(200); + assert.strictEqual(await usesOf(token), 0); + }); + + it('two requests that race for a one-use token issue at most one certificate', async () => { + const token = await mkToken(); + const csrs = await Promise.all([newCsr(), newCsr()]); + const results = await Promise.all(csrs.map((c) => enroll(c, {token: token.secret, identity: identity({macs: [mac()]})}))); + assert.deepStrictEqual(results.map((r) => r.status).sort(), [200, 202]); + assert.strictEqual(await usesOf(token), 0); + }); + }); + + describe('the deploy window', () => { + const hoursAgo = (h) => new Date(Date.now() - h * 3600000).toISOString(); + + it('issues for known-host-no-agent when the host was deployed within 24 hours', async () => { + const m = mac(); + await mkHost({macs: [bare(m)], deployed: hoursAgo(1)}); + const res = await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(200); + assert.strictEqual(res.body.status, 'issued'); + }); + + it('issues for rebind, and the host keeps its number', async () => { + const m = mac(); + const host = await mkHost({macs: [bare(m)], deployed: hoursAgo(2), agentFingerprint: crypto.randomBytes(32).toString('hex'), agentId: 987654}); + const res = await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(200); + assert.strictEqual(res.body.host_id, 987654); + assert.notStrictEqual((await hostOf(host.id)).agentFingerprint, host.agentFingerprint); + }); + + it('waits when the deploy is older than the window, in the future, or unset', async () => { + for (const deployed of [hoursAgo(25), hoursAgo(-5), '', 'not a date']) { + const m = mac(); + await mkHost({macs: [bare(m)], deployed}); + const res = await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(202); + assert.strictEqual(res.body.reason, 'known-host-no-agent', JSON.stringify(deployed)); + } + }); + + it('does not issue for unknown-host or identity-conflict', async () => { + const res = await enroll(await newCsr(), {identity: identity({macs: [mac()]})}).expect(202); + assert.strictEqual(res.body.reason, 'unknown-host'); + const serial = `MOCHA-${uniq()}`; + const m = mac(); + await mkHost({serial, deployed: hoursAgo(1)}); + await mkHost({macs: [bare(m)], deployed: hoursAgo(1)}); + const conflict = await enroll(await newCsr(), {identity: identity({system_serial: serial, macs: [m]})}).expect(202); + assert.strictEqual(conflict.body.reason, 'identity-conflict'); + }); + + it('follows the Setting FOG_AGENT_ENROLL_DEPLOY_WINDOW: a wider window issues, below 1 disables', async () => { + const m = mac(); + await mkHost({macs: [bare(m)], deployed: hoursAgo(30)}); + await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(202); + await put('FOG_AGENT_ENROLL_DEPLOY_WINDOW', '48'); + await enroll(await newCsr(), {identity: identity({macs: [m]})}).expect(200); + + const m2 = mac(); + await mkHost({macs: [bare(m2)], deployed: hoursAgo(1)}); + await put('FOG_AGENT_ENROLL_DEPLOY_WINDOW', '0'); + await enroll(await newCsr(), {identity: identity({macs: [m2]})}).expect(202); + }); + }); + + describe('the Host record', () => { + const collection = (model) => sails.getDatastore(model.datastore).manager.collection(model.tableName); + let admin; + + async function signIn(username, password) { + const agent = supertest.agent(app()); + let {body} = await agent.get('/csrfToken').expect(200); + await agent.post('/login').type('form').set(...HTML) + .send({username, password, _csrf: body._csrf}) + .expect(302).expect('Location', '/'); + ({body} = await agent.get('/csrfToken').expect(200)); + return {agent, csrf: body._csrf}; + } + before(async () => { admin = await signIn('mochatestadmin', 'mochatestadmin'); }); + + it('has the four indexes after a lift, and a second ensureIndexes does not fail', async () => { + const check = async () => { + const find = async (model, key) => (await collection(model).indexes()).find((i) => Object.keys(i.key).join() === key); + const fp = await find(sails.models.agentenrollment, 'fingerprint'); + const hash = await find(sails.models.agentenrolltoken, 'hash'); + const hostFp = await find(sails.models.host, 'agentFingerprint'); + const hostId = await find(sails.models.host, 'agentId'); + assert.strictEqual(fp && fp.unique, true); + assert.strictEqual(hash && hash.unique, true); + assert.ok(hostFp); + assert.notStrictEqual(hostFp.unique, true); + assert.strictEqual(hostId && hostId.unique, true); + assert.deepStrictEqual(hostId.partialFilterExpression, {agentId: {$gt: 0}}); + }; + await check(); + await sails.helpers.agent.ensureIndexes(); + await check(); + }); + + it('lets two hosts with no agent exist (agentId 0 is not indexed)', async () => { + const a = await mkHost(); + const b = await mkHost(); + assert.ok(!(a.agentId > 0) && !(b.agentId > 0)); + }); + + it('refuses a second host with the same agentId', async () => { + const a = await mkHost({agentId: 424242}); + assert.strictEqual(a.agentId, 424242); + await assert.rejects(mkHost({agentId: 424242}), (err) => err.code === 'E_UNIQUE'); + }); + + it('refuses a second row for one fingerprint', async () => { + const c = await newCsr(); + await Enrollment().create({fingerprint: c.fingerprint, csr: c.pem}); + await assert.rejects(Enrollment().create({fingerprint: c.fingerprint, csr: c.pem}), (err) => err.code === 'E_UNIQUE'); + }); + + it('lists the five fields as server-owned', () => { + assert.deepStrictEqual([...sails.models.host.serverOwned].sort(), ['agentCheckin', 'agentFingerprint', 'agentId', 'agentNotAfter', 'agentVersion']); + }); + + it('does not show the agent fields on the host edit page', async () => { + const host = await mkHost({agentFingerprint: 'a'.repeat(64), agentId: 515151}); + const res = await admin.agent.get(`/hosts/edit/${host.id}`).set(...HTML).expect(200); + assert.ok(res.text.includes('host-kernelArgs'), 'the page lists the other host fields'); + assert.ok(!/agent(Fingerprint|NotAfter|Version|Checkin|Id)|host-agent/i.test(res.text), 'no agent field is on the page'); + }); + + it('does not set the agent fields from a page save, POST /api/v1/host or PUT /api/v1/host/:id', async () => { + const evil = {agentFingerprint: 'e'.repeat(64), agentId: 616161, agentNotAfter: '2099-01-01 00:00:00', agentVersion: '6.6.6', agentCheckin: 99}; + const clean = (h) => { + assert.ok(!h.agentFingerprint, 'agentFingerprint'); + assert.ok(!(h.agentId > 0), 'agentId'); + assert.ok(!h.agentNotAfter, 'agentNotAfter'); + assert.ok(!h.agentVersion, 'agentVersion'); + assert.ok(!(h.agentCheckin > 0), 'agentCheckin'); + }; + + const created = await admin.agent.post('/api/v1/host').set(...AJAX).send(Object.assign({name: uniq()}, evil)).expect(200); + clean(await hostOf(created.body.id)); + + const host = await mkHost(); + await admin.agent.put(`/api/v1/host/${host.id}`).set(...AJAX).send(Object.assign({description: 'put'}, evil)).expect(200); + assert.strictEqual((await hostOf(host.id)).description, 'put'); + clean(await hostOf(host.id)); + + await admin.agent.post(`/hosts/edit/${host.id}`).type('form').set(...HTML) + .send(Object.assign({name: host.name, description: 'page', _csrf: admin.csrf}, evil)).expect(302); + assert.strictEqual((await hostOf(host.id)).description, 'page'); + clean(await hostOf(host.id)); + + const page = await admin.agent.post('/hosts/create').type('form').set(...HTML) + .send(Object.assign({name: uniq(), _csrf: admin.csrf}, evil)).expect(302); + clean(await hostOf(/\/hosts\/edit\/(\w+)/.exec(page.headers.location)[1])); + }); + + it('does not let a stock-less model through the generic API', async () => { + const c = await newCsr(); + await Enrollment().create({fingerprint: c.fingerprint, csr: c.pem}); + for (const model of ['agentenrollment', 'agentenrolltoken']) { + await admin.agent.get(`/api/v1/${model}`).set(...AJAX).expect(403); + } + }); + }); +}); diff --git a/test/support/agent-csr.js b/test/support/agent-csr.js new file mode 100644 index 0000000..46defe1 --- /dev/null +++ b/test/support/agent-csr.js @@ -0,0 +1,27 @@ +const crypto = require('crypto'); +const x509 = require('@peculiar/x509'); + +// A CSR as the fog-agent builds it: an ECDSA P-256 key and an empty subject +// (contract 4.3). Returns {pem, fingerprint, keys}. `fingerprint` is the key +// fingerprint that the enroll row is keyed by. Needs the lifted sails global. +const newKey = () => crypto.webcrypto.subtle.generateKey({name: 'ECDSA', namedCurve: 'P-256'}, true, ['sign', 'verify']); + +const csrFor = async (keys) => { + const csr = await x509.Pkcs10CertificateRequestGenerator.create({ + name: '', keys, signingAlgorithm: {name: 'ECDSA', hash: 'SHA-256'} + }); + const pem = csr.toString('pem'); + return {pem, fingerprint: sails.helpers.agent.keyFingerprint(pem), keys}; +}; + +const newCsr = async () => csrFor(await newKey()); + +// The same CSR with its last signature byte changed: it parses, but the +// self-signature does not verify. +const forge = (pem) => { + const der = Buffer.from(pem.replace(/-----[A-Z ]+-----|\s/g, ''), 'base64'); + der[der.length - 1] ^= 0x01; + return `-----BEGIN CERTIFICATE REQUEST-----\n${der.toString('base64').match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE REQUEST-----\n`; +}; + +module.exports = {newKey, csrFor, newCsr, forge};