@pathbit/agentdevkit 0.0.10 → 0.0.12

package/.pbai4devs/scripts/auditar-seguranca/tests/SMOKE.mjs

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { SecurityAudit } from '../SCRIPT.mjs';
+import { ToolManager } from '../../preparar-ferramentas/SCRIPT.mjs';
+import { zipFixture } from './zip-fixture.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const manager = new ToolManager({ root });
+for (const name of ['gitleaks', 'osv-scanner', 'opengrep']) manager.check(name);
+const base = join(root, '.agent-tests/security-smoke'); fs.mkdirSync(base, { recursive: true });
+const work = fs.mkdtempSync(join(base, 'run-'));
+const fixture = join(work, 'project'); fs.mkdirSync(fixture);
+const write = (file, bytes) => { fs.mkdirSync(dirname(file), { recursive: true }); fs.writeFileSync(file, bytes); };
+for (const file of ['scripts/preparar-ferramentas/SCRIPT.mjs', 'scripts/lib/native-release.mjs', 'scripts/lib/runtime.mjs', 'scripts/auditar-seguranca/rules/javascript.yml']) write(join(fixture, '.pbai4devs', file), fs.readFileSync(join(root, '.pbai4devs', file)));
+for (const name of ['gitleaks', 'osv-scanner', 'opengrep']) {
+  const source = join(root, '.pbai4devs/tools', name), target = join(fixture, '.pbai4devs/tools', name);
+  for (const file of ['TOOL.json', 'SCRIPT.mjs']) write(join(target, file), fs.readFileSync(join(source, file)));
+  const current = JSON.parse(fs.readFileSync(join(source, '.local/CURRENT.json')));
+  const definition = JSON.parse(fs.readFileSync(join(source, 'TOOL.json')));
+  for (const path of Object.values(definition.envPaths || {})) fs.mkdirSync(join(target, '.local', path), { recursive: true });
+  write(join(target, '.local/CURRENT.json'), fs.readFileSync(join(source, '.local/CURRENT.json')));
+  const version = `${current.version}-${current.platform}`;
+  fs.cpSync(join(source, '.local/versions', version), join(target, '.local/versions', version), { recursive: true });
+}
+const syntheticSecret = 'ghp_' + 'a2f80b357bba4272fc7bb1382e82cdb36045';
+write(join(fixture, 'app/index.js'), `import { exec } from 'node:child_process';
+function unsafe(req, db) {
+  eval(req.query.code);
+  exec(req.body.command);
+  db.query('select * from users where id=' + req.params.id);
+  const tls = { rejectUnauthorized: false };
+  return tls;
+}
+const apiKey = '${syntheticSecret}';
+`);
+const lock = version => JSON.stringify({ name: 'fixture', version: '1.0.0', lockfileVersion: 3, packages: { '': { name: 'fixture', version: '1.0.0', dependencies: { 'security-fixture-lib': version } }, 'node_modules/security-fixture-lib': { version, resolved: `https://registry.npmjs.org/security-fixture-lib/-/security-fixture-lib-${version}.tgz` } } });
+write(join(fixture, 'app/package-lock.json'), lock('1.0.0'));
+const audit = new SecurityAudit({ root: fixture });
+const vulnerability = { schema_version: '1.6.0', id: 'TEST-2099-0001', modified: '2025-01-01T00:00:00Z', published: '2025-01-01T00:00:00Z', summary: 'Synthetic vulnerability used only by local tests', affected: [{ package: { ecosystem: 'npm', name: 'security-fixture-lib' }, ranges: [{ type: 'SEMVER', events: [{ introduced: '0' }, { fixed: '1.0.1' }] }], versions: ['1.0.0'] }] };
+const archive = zipFixture({ 'TEST-2099-0001.json': JSON.stringify(vulnerability) });
+audit.fetcher = async () => new Response(archive);
+await audit.updateData(['npm']);
+const digest = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+const before = digest(join(fixture, 'app/index.js'));
+const bad = await audit.run({ target: 'app' });
+write(join(work, 'unsafe-report.json'), JSON.stringify(bad, null, 2));
+assert.equal(bad.status, 'findings', JSON.stringify(bad.checks));
+for (const check of bad.checks) assert.equal(check.status, 'findings', check.tool);
+assert.equal(digest(join(fixture, 'app/index.js')), before);
+assert.ok(!JSON.stringify(bad).includes(syntheticSecret));
+assert.ok(bad.findings.some(finding => finding.rule === 'TEST-2099-0001'));
+for (const id of ['pbai-eval-input', 'pbai-shell-input', 'pbai-sql-input', 'pbai-tls-verification-disabled']) assert.ok(bad.findings.some(finding => finding.rule === id), id);
+write(join(fixture, 'app/index.js'), `import { execFile } from 'node:child_process';
+function safe(req, db) {
+  JSON.parse(req.query.data);
+  execFile('printf', ['%s', req.body.message]);
+  db.query('select * from users where id = ?', [req.params.id]);
+  return { rejectUnauthorized: true };
+}
+`);
+write(join(fixture, 'app/package-lock.json'), lock('1.0.1'));
+const good = await audit.run({ target: 'app' });
+write(join(work, 'safe-report.json'), JSON.stringify(good, null, 2));
+assert.equal(good.status, 'passed', JSON.stringify(good.checks)); assert.equal(good.findings.length, 0);
+write(join(fixture, 'app/package-lock.json'), JSON.stringify({ name: 'fixture', version: '1.0.0', lockfileVersion: 3, packages: { '': { name: 'fixture', version: '1.0.0' } } }));
+const empty = await audit.run({ target: 'app', checks: ['dependencies'] });
+write(join(work, 'no-dependencies-report.json'), JSON.stringify(empty, null, 2));
+assert.equal(empty.status, 'not-applicable', JSON.stringify(empty.checks));
+const report = { status: 'passed', work, tools: bad.checks.map(item => ({ tool: item.tool, version: item.version })), positiveFindings: bad.findings.length, negativeFindings: good.findings.length, noDependencies: empty.status, offline: true, sourcePreserved: true };
+write(join(work, 'REPORT.json'), JSON.stringify(report, null, 2));
+console.log(JSON.stringify(report));

package/.pbai4devs/scripts/auditar-seguranca/tests/TEST.mjs

@@ -0,0 +1,247 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SecurityAudit, parseArgs, parseGitleaks, parseOsv, parseOpengrep, sanitizedEnvironment, safePath, snapshotSources, verifyDatabase } from '../SCRIPT.mjs';
+import { zipFixture } from './zip-fixture.mjs';
+import { validateOsvDatabase } from '../database-zip.mjs';
+
+const write = (path, text) => { fs.mkdirSync(dirname(path), { recursive: true }); fs.writeFileSync(path, text); };
+const toolPath = args => args[0].replaceAll('\\', '/');
+const advisory = (id = 'TEST-1', extra = {}) => JSON.stringify({ id, modified: '2026-01-01T00:00:00Z', affected: [], ...extra });
+const validZip = () => zipFixture({ 'TEST-1.json': advisory() });
+function fixture(t) {
+  const root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'pbai-security-')));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  assert.equal(spawnSync('git', ['init', '--quiet', root]).status, 0);
+  write(join(root, '.gitignore'), '/.agent-tests/\n');
+  write(join(root, 'app/index.js'), 'export const answer = 42;\n');
+  write(join(root, '.pbai4devs/scripts/auditar-seguranca/rules/javascript.yml'), 'rules: []\n');
+  for (const name of ['gitleaks', 'osv-scanner', 'opengrep']) write(join(root, `.pbai4devs/tools/${name}/SCRIPT.mjs`), '// fixture\n');
+  const manager = { root, check: () => ({ version: '1.0.0' }), entry: () => ({ envPaths: { OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY: 'data/osv' } }), local: () => join(root, '.pbai4devs/tools/osv-scanner/.local'), withLock: (_name, action) => action() };
+  const calls = [];
+  const execute = (_node, args, options) => {
+    calls.push({ args, options });
+    const payload = toolPath(args).includes('/gitleaks/') ? [] : toolPath(args).includes('/osv-scanner/') ? { results: [] }
+      : { results: [], errors: [], paths: { scanned: [join(options.cwd, 'source/index.js')] } };
+    const output = args.find(arg => arg.startsWith('--report-path=') || arg.startsWith('--output-file='));
+    if (output) fs.writeFileSync(output.slice(output.indexOf('=') + 1), JSON.stringify(payload));
+    return { status: 0, stdout: JSON.stringify(payload), stderr: '' };
+  };
+  return { root, manager, calls, execute, audit: new SecurityAudit({ root, manager, execute }) };
+}
+
+test('argumentos limitam checks, destinos e operacoes', () => {
+  assert.equal(parseArgs([]).command, 'help');
+  assert.deepEqual(parseArgs(['run', '--checks', 'sast,secrets,secrets']).checks, ['sast', 'secrets']);
+  assert.deepEqual(parseArgs(['update-data', '--ecosystems', 'NPM,go']).ecosystems, ['npm', 'Go']);
+  for (const args of [['scan'], ['run', '--checks', 'cloud'], ['run', '--checks', ''], ['check', '--target', '.'], ['run', '--ecosystems', 'npm'], ['update-data'], ['update-data', '--ecosystems', '../../etc'], ['run', '--target', '.', '--target', '.'], ['run', '--checks', 'sast', '--include-history']]) assert.throws(() => parseArgs(args));
+});
+
+test('ambiente nao encaminha tokens, proxies, Node options ou configuracoes externas', () => {
+  const env = sanitizedEnvironment({ PATH: '/bin', HOME: '/home/person', SystemRoot: 'C:\\Windows', AWS_ACCESS_KEY_ID: 'secret', GOOGLE_APPLICATION_CREDENTIALS: 'secret', SECRET: 'secret', NPM_TOKEN: 'secret', NODE_OPTIONS: '--require malicious', HTTPS_PROXY: 'secret', SEMGREP_RULES: 'https://remote', GITLEAKS_CONFIG: 'secret' });
+  assert.equal(env.PATH, '/bin'); assert.equal(env.HOME, '/home/person'); assert.equal(env.SystemRoot, 'C:\\Windows');
+  assert.ok(!JSON.stringify(env).includes('secret')); assert.equal(env.NODE_OPTIONS, undefined); assert.equal(env.SEMGREP_RULES, undefined);
+  assert.equal(env.OPENGREP_ENABLE_VERSION_CHECK, '0');
+});
+
+test('caminhos recusam escapes, links e output rastreado antes de executar', async t => {
+  const f = fixture(t); const outside = fs.mkdtempSync(join(tmpdir(), 'pbai-outside-')); t.after(() => fs.rmSync(outside, { recursive: true, force: true }));
+  fs.symlinkSync(outside, join(f.root, 'link'), process.platform === 'win32' ? 'junction' : undefined);
+  assert.throws(() => safePath(f.root, '../outside')); assert.throws(() => safePath(f.root, 'link/file.json'));
+  await assert.rejects(f.audit.run({ target: 'app', checks: ['secrets'], output: 'report.json' }));
+  fs.mkdirSync(join(f.root, '.agent-tests/security'), { recursive: true });
+  await assert.rejects(f.audit.run({ target: '.agent-tests', checks: ['secrets'] }), /conflita/);
+  await assert.rejects(f.audit.run({ target: '.agent-tests/security', checks: ['secrets'] }), /conflita/);
+  write(join(f.root, '.agent-tests/tracked.json'), '{}');
+  assert.equal(spawnSync('git', ['-C', f.root, 'add', '-f', '.agent-tests/tracked.json']).status, 0);
+  await assert.rejects(f.audit.run({ target: 'app', checks: ['secrets'], output: '.agent-tests/tracked.json' }));
+  assert.equal(f.calls.length, 0);
+});
+
+test('snapshot preserva originais e nao atravessa links nem diretorios gerados', t => {
+  const f = fixture(t); write(join(f.root, 'app/node_modules/excluded.js'), 'secret'); write(join(f.root, 'app/.semgrepignore'), '*');
+  fs.symlinkSync(join(f.root, 'app'), join(f.root, 'app/link'), process.platform === 'win32' ? 'junction' : 'dir');
+  const destination = join(f.root, '.agent-tests/snapshot'); fs.mkdirSync(destination, { recursive: true });
+  const data = snapshotSources(f.root, join(f.root, 'app'), destination);
+  assert.deepEqual(data.files.map(file => file.path), ['index.js']);
+  assert.equal(data.excluded.length, 3); assert.equal(fs.readFileSync(join(f.root, 'app/index.js'), 'utf8'), fs.readFileSync(join(destination, 'index.js'), 'utf8'));
+  assert.throws(() => snapshotSources(f.root, join(f.root, 'app'), destination, { maxFileBytes: 1 }));
+});
+
+test('parsers redigem segredos e recusam saidas invalidas ou falsas aprovacoes', () => {
+  const secret = 'a-secret-value-that-must-not-escape';
+  const gitleaks = parseGitleaks([{ RuleID: 'key', File: 'a.js', StartLine: 3, Secret: secret, Match: secret, Line: secret, Description: secret }], 1, '/tmp');
+  assert.equal(gitleaks.status, 'findings'); assert.ok(!JSON.stringify(gitleaks).includes(secret));
+  assert.throws(() => parseGitleaks([], 1, '/tmp')); assert.throws(() => parseGitleaks([], 2, '/tmp')); assert.throws(() => parseGitleaks([{ RuleID: 'x', File: '../escape' }], 1, '/tmp'));
+  assert.throws(() => parseGitleaks([{ RuleID: 'x', File: 'src/../../escape' }], 1, '/tmp'));
+  assert.equal(parseOsv({ results: [] }, 128, '/tmp').status, 'not-applicable'); assert.throws(() => parseOsv({ results: [] }, 127, '/tmp')); assert.throws(() => parseOsv({ results: [] }, 1, '/tmp'));
+  const osv = parseOsv({ results: [{ source: { path: 'package-lock.json' }, packages: [{ package: { name: 'demo', version: '1.0.0', ecosystem: 'npm' }, vulnerabilities: [{ id: 'TEST-1', details: secret }] }] }] }, 1, '/tmp');
+  assert.equal(osv.findings.length, 1); assert.ok(!JSON.stringify(osv).includes(secret));
+  const sast = parseOpengrep({ results: [{ check_id: 'pbai-eval-input', path: 'a.js', start: { line: 2 }, extra: { lines: secret, message: secret } }], errors: [], paths: { scanned: ['a.js'] } }, 1, '/tmp');
+  assert.equal(sast.findings.length, 1); assert.ok(!JSON.stringify(sast).includes(secret));
+  assert.throws(() => parseOpengrep({ results: [], errors: [{}], paths: { scanned: [] } }, 0, '/tmp'));
+  assert.throws(() => parseOpengrep({ results: [], errors: [] }, 0, '/tmp'));
+});
+
+test('Opengrep usa IDs e fingerprints estaveis sem caminhos de Linux, Windows ou macOS', () => {
+  const rules = ['pbai-eval-input', 'pbai-shell-input', 'pbai-sql-input', 'pbai-tls-verification-disabled'];
+  const prefixes = ['', 'home.runner.work.AgentDevKit.AgentDevKit..agent-tests.security-smoke.run-eu1Fdm..pbai4devs.scripts.auditar-seguranca.rules.',
+    'D.a.AgentDevKit.AgentDevKit..agent-tests.security-smoke.run-TpubGc..pbai4devs.scripts.auditar-seguranca.rules.',
+    'Users.person.Library.Project..agent-tests.security-smoke.run-macABC..pbai4devs.scripts.auditar-seguranca.rules.'];
+  const reports = prefixes.map(prefix => parseOpengrep({
+    results: rules.map((rule, index) => ({ check_id: `${prefix}${rule}`, path: 'src/handler.js', start: { line: index + 1 }, extra: { severity: 'ERROR' } })),
+    errors: [], paths: { scanned: ['src/handler.js'] },
+  }, 1, '/unused'));
+  for (const report of reports) {
+    assert.deepEqual(report, reports[0]);
+    assert.deepEqual(report.findings.map(item => item.rule), rules);
+    assert.equal(new Set(report.findings.map(item => item.fingerprint)).size, rules.length);
+    assert.doesNotMatch(JSON.stringify(report), /runner|person|run-eu1Fdm|run-TpubGc|run-macABC|AgentDevKit|pbai4devs|D\.a\./);
+  }
+});
+
+test('Opengrep rejeita regras desconhecidas e semelhantes sem divulgar o ID bruto', () => {
+  const unknown = ['unknown', 'pbai-eval-input-extra', 'prefix.pbai-eval-input.extra', 'prefix.pbai-unknown', '/private/person/pbai-eval-input', ''];
+  for (const check_id of unknown) {
+    assert.throws(() => parseOpengrep({ results: [{ check_id, path: 'src/handler.js', start: { line: 1 } }], errors: [], paths: { scanned: ['src/handler.js'] } }, 1, '/unused'),
+      error => error.message === 'Identificador de regra Opengrep desconhecido.' && error.publicMessage === error.message);
+  }
+});
+
+test('regra Opengrep desconhecida torna a auditoria incompleta sem vazar caminho local', async t => {
+  const f = fixture(t), check_id = 'Users.private-person.project.run-private.rules.unrecognized';
+  f.audit.execute = () => ({ status: 1, stdout: JSON.stringify({ results: [{ check_id, path: 'index.js', start: { line: 1 } }], errors: [], paths: { scanned: ['index.js'] } }), stderr: '' });
+  const report = await f.audit.run({ target: 'app', checks: ['sast'] });
+  assert.equal(report.status, 'incomplete'); assert.equal(report.exitCode, 2);
+  assert.deepEqual(report.findings, []); assert.equal(report.checks[0].status, 'not-run');
+  assert.doesNotMatch(JSON.stringify(report), /private-person|run-private|unrecognized/);
+});
+
+test('run usa argumentos locais e fecha incompleto quando ferramenta ou DB falta', async t => {
+  const f = fixture(t);
+  const result = await f.audit.run({ target: 'app', checks: ['secrets', 'sast'] });
+  assert.equal(result.status, 'passed'); assert.equal(result.exitCode, 0);
+  assert.ok(f.calls.every(call => call.options.shell === false && call.options.timeout > 0));
+  assert.ok(f.calls.some(call => call.args.includes('--disable-version-check') && call.args.includes('--no-git-ignore')));
+  assert.ok(f.calls.some(call => call.args.includes('--redact=100')));
+  assert.ok(!f.calls.some(call => call.args.some(arg => /metrics|https:\/\/|--autofix/.test(arg))));
+  assert.ok(fs.existsSync(join(f.root, result.report))); assert.ok(!fs.readdirSync(join(f.root, '.agent-tests/security')).some(name => name.startsWith('.work-')));
+  write(join(f.root, 'app/package-lock.json'), '{}');
+  const missingDb = await f.audit.run({ target: 'app', checks: ['dependencies'] });
+  assert.equal(missingDb.status, 'incomplete'); assert.equal(missingDb.exitCode, 2);
+  f.manager.check = () => { throw Error('Missing TOKEN=secret'); };
+  const missingTool = await f.audit.run({ target: 'app', checks: ['secrets'] });
+  assert.equal(missingTool.status, 'incomplete'); assert.ok(!JSON.stringify(missingTool).includes('TOKEN'));
+});
+
+test('alteracao da fonte durante a ferramenta invalida o resultado', async t => {
+  const f = fixture(t), execute = f.execute;
+  f.audit.execute = (...args) => { const result = execute(...args); write(join(f.root, 'app/index.js'), 'changed'); return result; };
+  const result = await f.audit.run({ target: 'app', checks: ['secrets'] });
+  assert.equal(result.status, 'incomplete'); assert.equal(result.exitCode, 2);
+});
+
+test('saida quebrada da ferramenta nao vira relatorio limpo', async t => {
+  const f = fixture(t); f.audit.execute = () => ({ status: 2, stdout: 'secret', stderr: 'secret' });
+  const result = await f.audit.run({ target: 'app', checks: ['sast'] });
+  assert.equal(result.exitCode, 2); assert.ok(!JSON.stringify(result).includes('secret'));
+});
+
+test('bases OSV atualizam explicitamente, validam hash e preservam anterior em falha', async t => {
+  const f = fixture(t); const zip = validZip(); let calls = 0;
+  f.audit.fetcher = async (url, options) => { calls++; assert.equal(url, 'https://osv-vulnerabilities.storage.googleapis.com/npm/all.zip'); assert.equal(options.redirect, 'error'); assert.equal(options.credentials, 'omit'); assert.deepEqual(Object.keys(options.headers), ['Accept']); return new Response(zip); };
+  assert.equal((await f.audit.updateData(['npm'])).status, 'passed');
+  const cache = join(f.manager.local(), 'data/osv'); const before = verifyDatabase(f.root, cache, 'npm'); assert.equal(calls, 1);
+  f.audit.fetcher = async () => new Response('broken'); await assert.rejects(f.audit.updateData(['npm']));
+  assert.deepEqual(verifyDatabase(f.root, cache, 'npm'), before);
+  const fake = Buffer.alloc(22); fake.writeUInt32LE(0x04034b50); fake.writeUInt32LE(0x06054b50, 4);
+  f.audit.fetcher = async () => new Response(fake); await assert.rejects(f.audit.updateData(['npm']));
+  assert.deepEqual(verifyDatabase(f.root, cache, 'npm'), before);
+  f.audit.fetcher = async () => new Response(zipFixture({ 'TEST-1.json': '{}' })); await assert.rejects(f.audit.updateData(['npm']));
+  assert.deepEqual(verifyDatabase(f.root, cache, 'npm'), before);
+  fs.appendFileSync(join(cache, 'osv-scalibr/npm/all.zip'), 'tampered'); assert.throws(() => verifyDatabase(f.root, cache, 'npm'));
+});
+
+test('query check nao escreve relatorios nem instala ferramentas', t => {
+  const f = fixture(t); const before = fs.readdirSync(f.root);
+  const result = f.audit.check(['secrets', 'sast']); assert.equal(result.exitCode, 0); assert.deepEqual(fs.readdirSync(f.root), before); assert.equal(f.calls.length, 0);
+});
+
+test('historico nunca amplia silenciosamente um target de subpasta', async t => {
+  const f = fixture(t);
+  await assert.rejects(f.audit.run({ target: 'app', checks: ['secrets'], includeHistory: true }), /raiz do repositorio/);
+  assert.equal(f.calls.length, 0);
+});
+
+test('bundles de texto continuam incluidos no snapshot de segredos', t => {
+  const f = fixture(t); write(join(f.root, 'app/dist/app.js'), 'bundle'); write(join(f.root, 'app/build/server.js'), 'server');
+  const destination = join(f.root, '.agent-tests/snapshot'); fs.mkdirSync(destination, { recursive: true });
+  const data = snapshotSources(f.root, join(f.root, 'app'), destination);
+  assert.ok(data.files.some(file => file.path === 'dist/app.js')); assert.ok(data.files.some(file => file.path === 'build/server.js'));
+});
+
+test('OSV recebe modo offline estrito e erro de outro scanner prevalece sobre achados', async t => {
+  const f = fixture(t); const zip = validZip(); f.audit.fetcher = async () => new Response(zip); await f.audit.updateData(['npm']);
+  write(join(f.root, 'app/package-lock.json'), '{}');
+  const execute = f.execute;
+  f.audit.execute = (node, args, options) => {
+    if (toolPath(args).includes('/osv-scanner/')) {
+      assert.ok(args.includes('--offline')); assert.ok(args.includes('--no-resolve')); assert.ok(args.includes('--all-packages'));
+      assert.ok(!args.some(arg => arg.includes('call-analysis') || arg.includes('licenses')));
+    }
+    return execute(node, args, options);
+  };
+  const result = await f.audit.run({ target: 'app', checks: ['dependencies'] }); assert.equal(result.status, 'not-applicable');
+  f.audit.execute = (_node, args) => {
+    if (toolPath(args).includes('/gitleaks/')) { const output = args.find(arg => arg.startsWith('--report-path=')); fs.writeFileSync(output.slice(output.indexOf('=') + 1), JSON.stringify([{ RuleID: 'key', File: 'index.js', StartLine: 1 }])); return { status: 1, stdout: '', stderr: '' }; }
+    return { status: 2, stdout: '{}', stderr: 'failure' };
+  };
+  const mixed = await f.audit.run({ target: 'app', checks: ['secrets', 'sast'] }); assert.equal(mixed.exitCode, 2); assert.equal(mixed.findings.length, 1);
+});
+
+test('OSV sem pacotes usa 128 explicito; erro sem JSON permanece incompleto', async t => {
+  const f = fixture(t); const zip = validZip(); f.audit.fetcher = async () => new Response(zip); await f.audit.updateData(['npm']);
+  write(join(f.root, 'app/package-lock.json'), '{}');
+  f.audit.execute = () => ({ status: 128, stdout: '', stderr: '' });
+  assert.equal((await f.audit.run({ target: 'app', checks: ['dependencies'] })).status, 'not-applicable');
+  f.audit.execute = () => ({ status: 127, stdout: '', stderr: '' });
+  assert.equal((await f.audit.run({ target: 'app', checks: ['dependencies'] })).status, 'incomplete');
+});
+
+test('ZIP e ZIP64 exigem estrutura, CRC, JSON OSV e limites validos', () => {
+  for (const options of [{}, { stored: true }, { descriptor: true }, { zip64: true }, { zip64: true, descriptor: true }]) {
+    const zip = zipFixture({ 'TEST-1.json': advisory(), 'TEST-2.json': advisory('TEST-2', { withdrawn: '2026-02-01T00:00:00Z', affected: undefined }) }, options);
+    assert.equal(validateOsvDatabase(zip).records, 2);
+  }
+  const zero = Buffer.alloc(22); zero.writeUInt32LE(0x04034b50); zero.writeUInt32LE(0x06054b50, 4);
+  assert.throws(() => validateOsvDatabase(zero));
+  assert.throws(() => validateOsvDatabase(zipFixture({ 'TEST-1.json': 'invalid' })));
+  assert.throws(() => validateOsvDatabase(zipFixture({ 'TEST-1.json': '{}' })));
+  assert.throws(() => validateOsvDatabase(zipFixture({ '../TEST-1.json': advisory() })));
+  assert.throws(() => validateOsvDatabase(zipFixture([['TEST-1.json', advisory()], ['TEST-1.json', advisory()]])));
+  const brokenCrc = validZip(); const central = brokenCrc.indexOf(Buffer.from([0x50, 0x4b, 0x01, 0x02]));
+  brokenCrc.writeUInt32LE(1, central + 16); assert.throws(() => validateOsvDatabase(brokenCrc));
+  const brokenPayload = validZip(); const payload = 30 + brokenPayload.readUInt16LE(26) + brokenPayload.readUInt16LE(28); brokenPayload[payload] ^= 0xff;
+  assert.throws(() => validateOsvDatabase(brokenPayload));
+  assert.throws(() => validateOsvDatabase(validZip(), { maxEntryBytes: 2 }));
+  assert.throws(() => validateOsvDatabase(validZip(), { maxTotalBytes: 2 }));
+});
+
+test('inventario final recusa adicao, remocao, renomeacao e mudanca de tipo', async t => {
+  const changes = {
+    addition: root => write(join(root, 'app/added-during-scan.js'), 'new'),
+    removal: root => fs.unlinkSync(join(root, 'app/index.js')),
+    rename: root => fs.renameSync(join(root, 'app/index.js'), join(root, 'app/renamed.js')),
+    type: root => { fs.unlinkSync(join(root, 'app/index.js')); fs.mkdirSync(join(root, 'app/index.js')); },
+    directory: root => fs.mkdirSync(join(root, 'app/new-folder')),
+  };
+  for (const [name, change] of Object.entries(changes)) await t.test(name, async subtest => {
+    const f = fixture(subtest), execute = f.execute;
+    f.audit.execute = (...args) => { const result = execute(...args); change(f.root); return result; };
+    const result = await f.audit.run({ target: 'app', checks: ['secrets'] });
+    assert.equal(result.status, 'incomplete'); assert.equal(result.exitCode, 2);
+  });
+});

package/.pbai4devs/scripts/auditar-seguranca/tests/zip-fixture.mjs

@@ -0,0 +1,45 @@
+import { deflateRawSync } from 'node:zlib';
+
+const crc32 = bytes => {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+};
+
+// Minimal deterministic ZIP builder for synthetic OSV database fixtures.
+export function zipFixture(entries, { zip64 = false, descriptor = false, stored = false } = {}) {
+  const files = [], index = []; let offset = 0;
+  const rows = Array.isArray(entries) ? entries : Object.entries(entries);
+  for (const [name, text] of rows) {
+    const filename = Buffer.from(name), bytes = Buffer.from(text), zipped = stored ? bytes : deflateRawSync(bytes), crc = crc32(bytes);
+    const localExtra = Buffer.alloc(zip64 ? 20 : 0), centralExtra = Buffer.alloc(zip64 ? 28 : 0);
+    if (zip64) {
+      localExtra.writeUInt16LE(1); localExtra.writeUInt16LE(16, 2); localExtra.writeBigUInt64LE(BigInt(bytes.length), 4); localExtra.writeBigUInt64LE(BigInt(zipped.length), 12);
+      centralExtra.writeUInt16LE(1); centralExtra.writeUInt16LE(24, 2); centralExtra.writeBigUInt64LE(BigInt(bytes.length), 4); centralExtra.writeBigUInt64LE(BigInt(zipped.length), 12); centralExtra.writeBigUInt64LE(BigInt(offset), 20);
+    }
+    const trailer = Buffer.alloc(descriptor ? zip64 ? 24 : 16 : 0);
+    if (descriptor) {
+      trailer.writeUInt32LE(0x08074b50); trailer.writeUInt32LE(crc, 4);
+      if (zip64) { trailer.writeBigUInt64LE(BigInt(zipped.length), 8); trailer.writeBigUInt64LE(BigInt(bytes.length), 16); }
+      else { trailer.writeUInt32LE(zipped.length, 8); trailer.writeUInt32LE(bytes.length, 12); }
+    }
+    const local = Buffer.alloc(30); local.writeUInt32LE(0x04034b50); local.writeUInt16LE(zip64 ? 45 : 20, 4); local.writeUInt16LE(descriptor ? 8 : 0, 6); local.writeUInt16LE(stored ? 0 : 8, 8);
+    local.writeUInt32LE(descriptor ? 0 : crc, 14); local.writeUInt32LE(zip64 ? 0xffffffff : descriptor ? 0 : zipped.length, 18); local.writeUInt32LE(zip64 ? 0xffffffff : descriptor ? 0 : bytes.length, 22); local.writeUInt16LE(filename.length, 26); local.writeUInt16LE(localExtra.length, 28);
+    files.push(local, filename, localExtra, zipped, trailer);
+    const central = Buffer.alloc(46); central.writeUInt32LE(0x02014b50); central.writeUInt16LE(zip64 ? 45 : 20, 4); central.writeUInt16LE(zip64 ? 45 : 20, 6); central.writeUInt16LE(descriptor ? 8 : 0, 8); central.writeUInt16LE(stored ? 0 : 8, 10);
+    central.writeUInt32LE(crc, 16); central.writeUInt32LE(zip64 ? 0xffffffff : zipped.length, 20); central.writeUInt32LE(zip64 ? 0xffffffff : bytes.length, 24); central.writeUInt16LE(filename.length, 28); central.writeUInt16LE(centralExtra.length, 30); central.writeUInt32LE(zip64 ? 0xffffffff : offset, 42);
+    index.push(central, filename, centralExtra); offset += local.length + filename.length + localExtra.length + zipped.length + trailer.length;
+  }
+  const table = Buffer.concat(index), end = Buffer.alloc(22); end.writeUInt32LE(0x06054b50);
+  end.writeUInt16LE(zip64 ? 0xffff : rows.length, 8); end.writeUInt16LE(zip64 ? 0xffff : rows.length, 10); end.writeUInt32LE(zip64 ? 0xffffffff : table.length, 12); end.writeUInt32LE(zip64 ? 0xffffffff : offset, 16);
+  const tail = [];
+  if (zip64) {
+    const wide = Buffer.alloc(56), locator = Buffer.alloc(20); wide.writeUInt32LE(0x06064b50); wide.writeBigUInt64LE(44n, 4); wide.writeUInt16LE(45, 12); wide.writeUInt16LE(45, 14);
+    wide.writeBigUInt64LE(BigInt(rows.length), 24); wide.writeBigUInt64LE(BigInt(rows.length), 32); wide.writeBigUInt64LE(BigInt(table.length), 40); wide.writeBigUInt64LE(BigInt(offset), 48);
+    locator.writeUInt32LE(0x07064b50); locator.writeBigUInt64LE(BigInt(offset + table.length), 8); locator.writeUInt32LE(1, 16); tail.push(wide, locator);
+  }
+  return Buffer.concat([...files, table, ...tail, end]);
+}

package/.pbai4devs/scripts/lib/README.md

@@ -7,3 +7,7 @@ description: Utilitários mínimos compartilhados das automações Node.js.
 `runtime.mjs` centraliza o requisito Node.js 24+, a raiz do repositório e a
 identificação do arquivo executado. Não instala runtimes nem configura a máquina.
 Também procura executáveis opcionais no PATH sem iniciar um shell.
+
+`managed-content.mjs` limita a propriedade do kit aos seus blocos Markdown;
+`managed-toml.mjs` aplica o mesmo contrato ao `prompt` de comandos Gemini.
+Texto externo, nomes existentes e metadados humanos permanecem preservados.

package/.pbai4devs/scripts/lib/gitignore.mjs

@@ -125,6 +125,34 @@ function artifactPolicy(templateFile) {
   return patterns;
 }
 
+function privateClientPolicy(templateFile, roots) {
+  const adjacent = join(dirname(templateFile), 'agents.ignore');
+  const source = checkedLocalPath(localStat(adjacent) ? adjacent : fileURLToPath(new URL('../../templates/gitignore/agents.ignore', import.meta.url)));
+  const section = readFileSync(source, 'utf8').split(/^## Estado local, caches e credenciais conhecidas\r?$/m)[1]?.split(/^## /m)[0];
+  const patterns = section?.split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+  if (!patterns?.length || patterns.some(pattern => !/^(?:!?\*\*\/|\/)/.test(pattern) || /[\\\x00-\x1f]/.test(pattern) || pattern.split('/').includes('..'))) throw new Error('Secao de estado local invalida em agents.ignore.');
+  const rules = [], probes = [];
+  for (const root of roots) for (const pattern of patterns) {
+    const negative = pattern.startsWith('!'), rule = pattern.replace(/^!/, '').replace(/^\//, '');
+    rules.push(`${negative ? '!' : ''}/${escapePattern(root)}/${rule}`);
+    if (negative) continue;
+    const stem = rule.replace(/^\*\*\//, '').replace(/\[([^\]]+)\]/g, (_match, letters) => letters[0]).replace(/\*/g, 'agentdevkit-private-probe').replace(/\?/g, 'x');
+    probes.push(`${root}/${stem}${stem.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+    if (rule.startsWith('**/')) probes.push(`${root}/.agentdevkit-ignore-probes/${stem}${stem.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+  }
+  return { rules, probes };
+}
+
+function safeIgnoreProbe(root, path) {
+  let parent = root;
+  for (const part of path.split('/').slice(0, -1)) {
+    parent = join(parent, part);
+    const item = localStat(parent);
+    if (item && !item.isDirectory()) return false;
+  }
+  return true;
+}
+
 function artifactProbes(root, patterns) {
   const probes = new Set();
   for (const pattern of patterns) {
@@ -233,10 +261,14 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const artifacts = artifactPolicy(templateFile);
   if (template.split('{{OUTPUTS}}').length !== 2) throw new Error('local.ignore exige um unico {{OUTPUTS}}.');
   if (template.split('{{ROOTS}}').length > 2) throw new Error('local.ignore permite um unico {{ROOTS}}.');
+  // A client directory can also contain human instructions and settings. Only
+  // whole files owned by the kit belong in the local output exclusion list.
+  const roots = [];
   const localPolicy = join(templateRoot || root, '.pbai4devs/templates/clients/ADAPTERS.json');
   const policy = JSON.parse(readFileSync(checkedLocalPath(localStat(localPolicy) ? localPolicy : fileURLToPath(new URL('../../templates/clients/ADAPTERS.json', import.meta.url))), 'utf8'));
-  const roots = [...new Set(policy.adapters.flatMap(adapter => [adapter.root, ...(adapter.extraRoots || [])]))].filter(path => !['.github', '.vscode'].includes(path));
-  if (roots.some(path => typeof path !== 'string' || !/^\.[a-z0-9][a-z0-9-]*$/.test(path) || ['.git', '.pbai4devs', '.agent-tests'].includes(path))) throw new Error('Raiz de cliente invalida para exclusao.');
+  const clientRoots = [...new Set(policy.adapters.flatMap(adapter => [adapter.root, ...(adapter.extraRoots || [])]))];
+  if (clientRoots.some(path => typeof path !== 'string' || !/^\.[a-z0-9][a-z0-9-]*$/.test(path) || ['.git', '.pbai4devs', '.agent-tests'].includes(path))) throw new Error('Raiz de cliente invalida para exclusao.');
+  const privateClients = privateClientPolicy(templateFile, clientRoots);
   const paths = [...new Set([...outputs.map(checkedOutput), ...template.split(/\r?\n/).filter(line => line.startsWith('/')).map(line => checkedOutput(line.slice(1)))])].sort();
   const info = gitCommand(resolved.parent, ['rev-parse', '--show-toplevel', '--git-path', 'info/exclude']);
   let location = null;
@@ -256,13 +288,18 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const id = createHash('sha256').update(root).digest('hex').slice(0, 16);
   const first = `# BEGIN AGENTDEVKIT LOCAL ${id}`, last = `# END AGENTDEVKIT LOCAL ${id}`;
   const fixed = template.replace('{{ROOTS}}', roots.map(path => `/${path}/`).join('\n')).replace('{{OUTPUTS}}', paths.filter(path => !roots.some(root => path === root || path.startsWith(root + '/'))).map(path => `/${escapePattern(path)}`).join('\n'))
+    + '\n# Estado privado dos clientes\n' + privateClients.rules.join('\n') + '\n'
     + '\n# Resultados e arquivos temporarios\n' + artifacts.map(pattern => `/${pattern}`).join('\n') + '\n';
-  const body = fixed.split(/\r?\n/).map(line => location?.prefix && line.startsWith('/') ? `/${escapePattern(location.prefix)}${line}` : line).join('\n');
+  const body = fixed.split(/\r?\n/).map(line => {
+    if (!location?.prefix) return line;
+    if (line.startsWith('!/')) return `!/${escapePattern(location.prefix)}${line.slice(1)}`;
+    return line.startsWith('/') ? `/${escapePattern(location.prefix)}${line}` : line;
+  }).join('\n');
   const target = location?.exclude ?? checkedLocalPath(join(root, '.gitignore'));
   const before = localRead(target), after = localBlock(before, first, last, body);
   const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
-  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
+  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...privateClients.probes.filter(path => safeIgnoreProbe(root, path)), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
   const wanted = new Set(probes.map(path => location?.prefix ? `${location.prefix}/${path}` : path));
   if (location && !before?.includes(first) && !localRead(join(root, '.gitignore'))?.includes(first)) {
     const ignored = ignoreMatches(location, [...probes, ...artifactPaths]);

package/.pbai4devs/scripts/lib/managed-content.mjs

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { readdirSync } from 'node:fs';
+
+export const managedBegin = '<!-- BEGIN AGENTDEVKIT -->';
+export const managedEnd = '<!-- END AGENTDEVKIT -->';
+const digest = value => createHash('sha256').update(value).digest('hex');
+const fail = message => { throw Object.assign(new Error(message), { code: 'E_MANAGED_BLOCK' }); };
+
+export function canonicalEntrypoint(path) {
+  return ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].find(name => name.toLowerCase() === path.toLowerCase()) || null;
+}
+
+export function resolveEntrypoint(root, canonical) {
+  if (!canonicalEntrypoint(canonical)) fail(`Entrada desconhecida: ${canonical}`);
+  let names;
+  try { names = readdirSync(root); }
+  catch (error) { if (error.code === 'ENOENT') return canonical; throw error; }
+  const matches = names.filter(name => name.toLowerCase() === canonical.toLowerCase());
+  if (matches.length > 1) fail(`Entradas ambiguas: ${matches.sort().join(', ')}`);
+  return matches[0] || canonical;
+}
+
+export function entrypointReference(root, path) {
+  const canonical = canonicalEntrypoint(path);
+  if (canonical === 'AGENTS.md') return 'Leia e siga [.pbai4devs/INSTRUCTIONS.md](.pbai4devs/INSTRUCTIONS.md).';
+  if (canonical === 'CLAUDE.md') return `@${resolveEntrypoint(root, 'AGENTS.md')}`;
+  if (canonical === 'GEMINI.md') return `@./${resolveEntrypoint(root, 'AGENTS.md')}`;
+  fail(`Entrada desconhecida: ${path}`);
+}
+
+export function renderEntrypointImports(root, text) {
+  const name = resolveEntrypoint(root, 'AGENTS.md');
+  return text.replace(/^(@(?:\.\/)?)AGENTS\.md(?=\r?$)/gim, (_match, prefix) => `${prefix}${name}`);
+}
+
+export function managedText(value) {
+  const text = Buffer.isBuffer(value) ? new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(value) : String(value ?? '');
+  if (text.includes('\0')) fail('Conteudo binario nao pode receber instrucoes Markdown.');
+  return text;
+}
+
+function locate(value) {
+  const text = managedText(value);
+  let fence = null, start = null, finish = null, offset = 0;
+  for (const match of text.matchAll(/([^\r\n]*)(\r\n|\r|\n|$)/g)) {
+    if (!match[0]) continue;
+    const line = match[1];
+    const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) fence = null;
+    } else if (marker) fence = marker[1];
+    else if (line === managedBegin) {
+      if (start !== null || finish !== null) fail('Marcadores AgentDevKit duplicados.');
+      start = offset;
+    } else if (line === managedEnd) {
+      if (start === null || finish !== null) fail('Marcadores AgentDevKit incompletos.');
+      finish = offset + line.length;
+    }
+    offset += match[0].length;
+  }
+  if ((start === null) !== (finish === null)) fail('Marcadores AgentDevKit incompletos.');
+  return { text, start, finish, fence, block: start === null ? null : text.slice(start, finish) };
+}
+
+export function extractManagedBlock(value) { return locate(value).block; }
+export function managedBlockDigest(value) { const block = extractManagedBlock(value); return block === null ? null : digest(block); }
+
+export function mergeManagedContent(value, body, { expectedHash } = {}) {
+  const current = locate(value), eol = current.text.match(/\r\n|\n|\r/)?.[0] || '\n';
+  const content = managedText(body).trim().replace(/\r\n|\r|\n/g, eol);
+  if (!content || content.includes(managedBegin) || content.includes(managedEnd)) fail('Referencia AgentDevKit invalida.');
+  const block = `${managedBegin}${eol}${content}${eol}${managedEnd}`;
+  if (current.block !== null && (expectedHash ? digest(current.block) !== expectedHash : current.block !== block)) fail('Bloco AgentDevKit alterado; conteudo preservado.');
+  if (current.fence && current.block === null) fail('Bloco de codigo Markdown nao fechado; conteudo preservado.');
+  const separator = !current.text || current.text.endsWith(eol + eol) ? '' : /[\r\n]$/.test(current.text) ? eol : eol + eol;
+  const text = current.block === null ? `${current.text}${separator}${block}${eol}`
+    : current.text.slice(0, current.start) + block + current.text.slice(current.finish);
+  return { text, block, sha256: digest(block), changed: text !== current.text };
+}
+
+export function stripManagedContent(value, expectedHash) {
+  const current = locate(value);
+  if (current.block === null) return current.text;
+  if (!expectedHash || digest(current.block) !== expectedHash) fail('Bloco AgentDevKit alterado; conteudo preservado.');
+  return current.text.slice(0, current.start) + current.text.slice(current.finish);
+}