Getting started

npm install attestium

const {fileTree, ProcessIntegrity} = require('attestium');

(async () => {
  // Every file under ./app: SHA-256, git mode, symbolic links recorded, never followed.
  const {entries, errors} = await fileTree.walkTree('./app');
  for (const entry of entries) {
    console.log(entry.mode, entry.sha256.slice(0, 12), entry.path);
  }

  console.log(`${errors.length} unreadable`);

  // This process: memory compared with the files it maps, injection
  // vectors, debuggers, open memfd objects, listening sockets.
  const report = new ProcessIntegrity().checkAll(process.pid);
  console.log(report.runtime, report.findings);

  // A clean report means something only when every check ran.
  console.log(report.passed ? 'passed' : 'not passed', report.incomplete);
})();

const os = require('node:os');
const {evidence, util} = require('attestium');

const nonce = util.generateNonce();
const document = {
  type: evidence.TYPE,
  version: evidence.VERSION,
  nonce,
  collectedAt: new Date().toISOString(),
  attester: {name: 'example-attester', version: '1.0.0'},
  host: {hostname: os.hostname(), kernel: os.release()},
  services: [],
  executables: [],
  libraries: [],
};
document.evidenceDigest = evidence.evidenceDigest(document);

console.log(evidence.validateEvidence(document)); // {valid: true, errors: []}
console.log(evidence.evidenceDigest(document) === document.evidenceDigest); // true

document.host.hostname = 'other';
console.log(evidence.evidenceDigest(document) === document.evidenceDigest); // false

// attester.js
const fs = require('node:fs');
const os = require('node:os');
const {evidence, fileTree, util, ProcessIntegrity} = require('attestium');

async function hashDirectory(root) {
  const {entries, errors} = await fileTree.walkTree(root, {
    exclude: relative => relative === '.git' || relative === 'node_modules',
  });
  const files = {};
  for (const entry of entries) {
    const hash = entry.type === 'symlink' ? `symlink:${entry.target}` : entry.sha256;
    util.setOwn(files, entry.path, [hash, entry.mode]);
  }

  return {files, fileCount: entries.length, errors};
}

function inspectProcesses(realRoot) {
  const inspector = new ProcessIntegrity();
  const processes = [];
  for (const info of inspector.listProcesses({cwdPrefix: realRoot})) {
    const report = inspector.checkAll(info.pid);
    processes.push({
      pid: Number(info.pid),
      ppid: info.ppid,
      uid: info.uid,
      cwd: info.cwd,
      exe: info.exe,
      exeDeleted: Boolean(info.exeDeleted),
      cmdline: info.cmdline.slice(0, 32).map(argument => argument.slice(0, 512)),
      startTime: new Date(info.startTimeMs).toISOString(),
      runtime: report.runtime,
      integrity: {
        passed: report.passed,
        findings: report.findings.map(finding => ({type: finding.type, severity: finding.severity, detail: String(finding.detail)})),
        incomplete: report.incomplete,
        libraries: report.memoryMaps.libraries || [],
      },
    });
  }

  return processes;
}

async function hashRunningFiles(processes) {
  const executables = new Map();
  const libraries = new Map();
  for (const item of processes) {
    // Read the executable through /proc/<pid>/exe: the file the process
    // runs, even if its path now names another file.
    if (item.exe && !executables.has(item.exe)) {
      executables.set(item.exe, {path: item.exe, container: null, ...await hashOrError(() => fs.promises.readFile(`/proc/${item.pid}/exe`))});
    }

    for (const library of item.integrity.libraries) {
      if (library !== item.exe && !libraries.has(library)) {
        libraries.set(library, {path: library, container: null, ...await hashOrError(() => fs.promises.readFile(library))});
      }
    }
  }

  return {executables: [...executables.values()], libraries: [...libraries.values()]};
}

async function hashOrError(read) {
  try {
    return {sha256: util.sha256(await read())};
  } catch (error) {
    return {error: error.code || error.message};
  }
}

async function collect(nonce, {name, root}) {
  const collectedAt = new Date().toISOString();
  const realRoot = fs.realpathSync(root);
  const processes = inspectProcesses(realRoot);
  const document = {
    type: evidence.TYPE,
    version: evidence.VERSION,
    nonce: util.normalizeNonce(nonce),
    collectedAt,
    attester: {name: 'example-attester', version: '1.0.0', platform: process.platform, arch: process.arch, node: process.version},
    host: {hostname: os.hostname(), kernel: os.release()},
    services: [{
      name,
      kind: 'directory',
      root,
      realRoot,
      git: {commit: null, error: 'not collected'},
      ...await hashDirectory(root),
      installs: [],
      processes,
      userProcesses: [],
    }],
    ...await hashRunningFiles(processes),
  };
  document.evidenceDigest = evidence.evidenceDigest(document);
  return document;
}

module.exports = {collect};

// attester-command.js
const {collect} = require('./attester');

(async () => {
  // sshd puts the command the verifier asked for in SSH_ORIGINAL_COMMAND.
  const match = /^check ([\da-f]+)$/.exec(process.env.SSH_ORIGINAL_COMMAND || '');
  if (!match) {
    console.error('Expected "check <nonce>"');
    process.exitCode = 2;
    return;
  }

  const document = await collect(match[1], {name: 'app', root: '/srv/app'});
  process.stdout.write(`${JSON.stringify(document)}\n`);
})().catch(error => {
  console.error(error.message);
  process.exitCode = 1;
});

restrict,command="node /opt/attester/attester-command.js" ssh-ed25519 AAAA... verifier

// verifier.js
const {evidence} = require('attestium');

function appraise(document, {nonce, maxAgeMs = 300_000, service, manifest, pinned = new Set()}) {
  const fail = [];
  const inconclusive = [];

  // 1. Shape, freshness and binding, before any other field is used.
  const shape = evidence.validateEvidence(document);
  if (!shape.valid) {
    return {status: 'fail', fail: shape.errors, inconclusive};
  }

  if (document.nonce !== nonce) {
    fail.push('evidence answers another nonce');
  }

  const age = Date.now() - Date.parse(document.collectedAt);
  if (!(age >= -60_000 && age <= maxAgeMs)) {
    fail.push('evidence is outside the accepted time window');
  }

  if (evidence.evidenceDigest(document) !== document.evidenceDigest) {
    fail.push('evidence digest does not match its contents');
  }

  if (fail.length > 0) {
    return {status: 'fail', fail, inconclusive};
  }

  // 2. Every file of the service against the reference.
  const record = document.services.find(item => item.name === service);
  if (!record || record.kind !== 'directory') {
    return {status: 'fail', fail: [`no directory service named ${service}`], inconclusive};
  }

  for (const [file, [hash, mode]] of Object.entries(manifest.files)) {
    const found = Object.hasOwn(record.files, file) ? record.files[file] : null;
    if (!found) {
      fail.push(`missing: ${file}`);
    } else if (found[0] !== hash || found[1] !== mode) {
      fail.push(`modified: ${file}`);
    }
  }

  for (const file of Object.keys(record.files)) {
    if (!Object.hasOwn(manifest.files, file)) {
      fail.push(`not in the reference: ${file}`);
    }
  }

  if (record.truncated || record.errors.length > 0) {
    inconclusive.push(`${record.errors.length} file(s) could not be read`);
  }

  // 3. Every process: critical findings fail, checks that did not run are inconclusive.
  for (const item of record.processes) {
    for (const finding of item.integrity.findings.filter(finding => finding.severity === 'critical')) {
      fail.push(`process ${item.pid}: ${finding.type} ${finding.detail}`);
    }

    for (const missing of item.integrity.incomplete) {
      inconclusive.push(`process ${item.pid}: ${missing.check} did not run (${missing.error})`);
    }
  }

  // 4. Every running file must be explained; here only by a pinned hash.
  for (const file of [...document.executables, ...document.libraries]) {
    if (file.error) {
      inconclusive.push(`${file.path}: ${file.error}`);
    } else if (!pinned.has(file.sha256)) {
      inconclusive.push(`${file.path}: not explained by any reference`);
    }
  }

  const status = fail.length > 0 ? 'fail' : (inconclusive.length > 0 ? 'inconclusive' : 'pass');
  return {status, fail, inconclusive};
}

module.exports = {appraise};

// verify.js
const {spawnSync} = require('node:child_process');
const {evidence, util} = require('attestium');
const {appraise} = require('./verifier');

(async () => {
  // The reference: the public commit, checked out by the verifier.
  const manifest = await evidence.createManifest('./reference', {repository: 'example/app', commit: 'a'.repeat(40)});

  const nonce = util.generateNonce();
  // The verifier's own key, and the server's host key pinned in ./known_hosts:
  // an unknown or changed host key fails instead of asking.
  const ssh = spawnSync('ssh', [
    '-F', 'none',
    '-i', 'verifier_key',
    '-o', 'IdentitiesOnly=yes',
    '-o', 'BatchMode=yes',
    '-o', 'StrictHostKeyChecking=yes',
    '-o', 'UserKnownHostsFile=known_hosts',
    '-o', 'ForwardAgent=no',
    '-o', 'ClearAllForwardings=yes',
    '-T', '--', 'attester@server.example.com', `check ${nonce}`,
  ], {encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 600_000});
  if (ssh.status !== 0) {
    throw new Error(`ssh failed: ${ssh.stderr || ssh.error}`);
  }

  const document = JSON.parse(ssh.stdout);

  const result = appraise(document, {nonce, service: 'app', manifest});
  console.log(result.status);
  console.log(result);
})();

ssh-keygen -t ed25519 -N '' -C verifier -f verifier_key     # verifier_key.pub goes into authorized_keys
ssh-keyscan -t ed25519 server.example.com > known_hosts    # over a path you trust; compare the fingerprint

node verify.js

const {ReleaseVerification} = require('attestium');

(async () => {
  // Compares process.execPath with bin/node inside the official archive.
  // In a verifier, pass {sha256, version, platform, arch} from the evidence.
  const result = await new ReleaseVerification().verifyNodeRelease();
  console.log(result.passed, result.details.officialSource);
})();