Compare commits

...
Author SHA1 Message Date
james.maesandCodex 17c94592d9 ci: centralize branch-aware QBit source scanning
Co-Authored-By: Codex <noreply@openai.com>
2026-10-21 09:29:04 -05:00
james.maesandCodex 9906c8f120 fix: audit explicitly selected repository branches (#62)
Co-authored-by: Codex <noreply@openai.com>
2026-10-21 09:15:33 -05:00
9 changed files with 289 additions and 12 deletions

No files matched your search

+1
View File
@@ -55,6 +55,7 @@ jobs:
python3 tests/test_voyage_profile.py
python3 tests/test_next_native.py
python3 tests/test_auxiliary_workflows.py
python3 tests/test_qbit_codeql.py
python3 tests/test_intellij_plugin.py
python3 tests/test_workflow_lint.py
python3 tests/test_business_e2e.py
+58
View File
@@ -0,0 +1,58 @@
name: QBit CodeQL
'on':
workflow_call:
permissions:
contents: read
actions: read
security-events: write
packages: read
jobs:
analyze:
name: Analyze branch source
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- name: Select languages present in this checkout
id: languages
run: |
python3 <<'PY'
import os
from pathlib import PurePosixPath
import subprocess
import sys
files = subprocess.check_output(['git', 'ls-files', '-z']).decode('utf-8').split('\0')
extensions = {PurePosixPath(name).suffix.lower() for name in files if name}
languages = []
if extensions & {'.java', '.kt', '.kts'}:
languages.append('java-kotlin')
if extensions & {'.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts'}:
languages.append('javascript-typescript')
if '.py' in extensions:
languages.append('python')
if any((name.startswith('.github/workflows/') and PurePosixPath(name).suffix in {'.yml', '.yaml'})
or PurePosixPath(name).name in {'action.yml', 'action.yaml'} for name in files if name):
languages.append('actions')
if not languages:
sys.exit('No supported source in this branch; classify placeholders before enabling QBit scanning')
build_mode = 'autobuild' if extensions & {'.kt', '.kts'} else 'none'
with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as output:
output.write('languages=' + ','.join(languages) + '\n')
output.write('build-mode=' + build_mode + '\n')
PY
- uses: actions/setup-java@v4
if: steps.languages.outputs.build-mode == 'autobuild'
with:
distribution: temurin
java-version: '21'
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
with:
languages: ${{ steps.languages.outputs.languages }}
build-mode: ${{ steps.languages.outputs.build-mode }}
- name: Build Kotlin sources
if: steps.languages.outputs.build-mode == 'autobuild'
uses: github/codeql-action/autobuild@v4
- name: Analyze source
uses: github/codeql-action/analyze@v4
+1
View File
@@ -64,6 +64,7 @@ test-pipelines: pack
python3 tests/test_voyage_profile.py
python3 tests/test_next_native.py
python3 tests/test_auxiliary_workflows.py
python3 tests/test_qbit_codeql.py
python3 tests/test_intellij_plugin.py
python3 tests/test_workflow_lint.py
python3 tests/test_business_e2e.py
+12
View File
@@ -3,6 +3,18 @@
`tools/audit_estate.py` classifies repositories from explicit mappings and observed source.
It never changes consumers, branch rules or publication settings.
Source auditing reads the repository's current default branch unless
`--live --source-branch main` (or an explicit `release/...` or `hotfix/...` branch)
is supplied. Run separate audits for each maintained source branch: a clean
default-branch report does not establish conformity on main or release branches.
The selected branch is resolved to an immutable commit before any files are read.
Reports identify both `source_branch` and the repository's `default_branch`;
the manifest's `default_branch` must still match the repository default.
Unavailable selected branches remain unknown without falling back to default.
Explicit branch selection requires live lookup and cannot relabel an offline SHA.
Required-check policy still controls which branch settings are inspected;
`--source-branch` changes source selection, not that enforcement policy.
- Circle profiles include android, mcp-policy and marketing. Their manifest and canonical
setup caller remain mandatory; a missing configuration is a finding.
- MCP, business-platform and the organization `.github` repository use approved native
+12
View File
@@ -0,0 +1,12 @@
# Shared QBit source scanning
Generate the thin caller with `python3 src/scripts/generate_auxiliary_workflow.py qbit-codeql --ref <immutable-worker-sha>`.
The reusable worker selects supported languages from tracked files in the actual checked-out branch. Historical Java branches therefore do not request an absent Actions database. Java, JavaScript/TypeScript, Python and Actions share one job; Kotlin selects an actual build instead of silently omitting Kotlin from no-build Java analysis.
The caller scans pull requests, main/develop/release/hotfix pushes and weekly, cancels superseded PR scans, and contains no scan implementation. Set `codeql_worker_sha` in the estate enforcement policy to require the exact canonical caller independently of other native worker pins. Existing default-setup repositories remain unchanged until migrated.
Roll out to both active default and maintained branches. Verify the worker on representative branch contents and preserve existing query coverage before replacing GitHub default setup; do not run duplicate default and advanced scanners permanently. Default setup cannot select languages independently for historical branches. A branch with no supported application or workflow source is a placeholder to classify, not a passing application scan.
Local tests execute the embedded language-selection step against real git indexes, including absent Actions, untracked generated files, mixed source, Kotlin and placeholders. Hosted CodeQL database creation and SARIF upload must also pass before claiming rollout completion.
References: [GitHub setup types](https://docs.github.com/en/code-security/concepts/code-scanning/setup-types) and [CodeQL build modes](https://docs.github.com/en/code-security/reference/code-scanning/codeql/build-options-for-compiled-languages).
+41 -1
View File
@@ -263,7 +263,7 @@
},
"concurrency": {
"group": "e2e-${{ github.ref }}",
"cancel-in-progress": "${{ github.event_name == 'pull_request' }}"
"cancel-in-progress": "${{ github.event_name == 'pull_request' }}"
},
"jobs": {
"validate": {
@@ -427,5 +427,45 @@
}
}
}
},
"qbit-codeql": {
"repository": null,
"profile": "qbit",
"path": ".github/workflows/codeql.yml",
"caller": {
"name": "CodeQL",
"on": {
"push": {
"branches": [
"main",
"develop",
"release/**",
"hotfix/**"
]
},
"pull_request": {},
"schedule": [
{
"cron": "41 16 * * 0"
}
],
"workflow_dispatch": {}
},
"permissions": {
"contents": "read",
"actions": "read",
"security-events": "write",
"packages": "read"
},
"concurrency": {
"group": "codeql-${{ github.event.pull_request.number || github.ref }}",
"cancel-in-progress": "${{ github.event_name == 'pull_request' }}"
},
"jobs": {
"analyze": {
"uses": "QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@WORKER_SHA"
}
}
}
}
}
+73
View File
@@ -26,6 +26,79 @@ class Snapshot:
class AuditTests(unittest.TestCase):
def test_qbit_scanner_policy_requires_exact_canonical_worker(self):
entry = dict(ENTRY, name='qbit-help', nameWithOwner='QRun-IO/qbit-help')
manifest = {'profile': 'qbit', 'orb_version': VERSION, 'default_branch': 'develop',
'publish': {'snapshot': False, 'release_candidate': False, 'release': False}}
files = {'.qqq-ci.yml': audit.generator.yaml.safe_dump(manifest),
'.circleci/config.yml': audit.generator.yaml.safe_dump(audit.standard.canonical_caller('qbit', VERSION))}
policy = dict(POLICY, codeql_worker_sha='b' * 40)
report = audit.audit(entry, Snapshot(files), VERSION, SHA, policy)
self.assertTrue(any(f['code'] == 'missing_native_maintenance_bridge' for f in report['findings']))
files['.github/workflows/codeql.yml'] = audit.generator.yaml.safe_dump(audit.auxiliary.canonical('qbit-codeql', 'b' * 40), sort_keys=False)
self.assertEqual([], audit.audit(entry, Snapshot(files), VERSION, SHA, policy)['findings'])
files['.github/workflows/codeql.yml'] = files['.github/workflows/codeql.yml'].replace('b' * 40, 'a' * 40)
report = audit.audit(entry, Snapshot(files), VERSION, SHA, policy)
self.assertTrue(any(f['code'] == 'native_maintenance_bridge_drift' for f in report['findings']))
def test_live_snapshot_reads_requested_branch_and_keeps_default_identity(self):
entry = dict(ENTRY, sourceBranch='release/1.2')
replies = [{'default_branch': 'develop', 'archived': False}, {'sha': SHA},
{'truncated': False, 'tree': []}]
with patch.object(audit, 'gh', side_effect=replies) as gh:
snapshot = audit.Snapshot(entry, live=True)
self.assertEqual('develop', snapshot.default_branch)
self.assertEqual('release/1.2', snapshot.branch)
self.assertEqual('repos/QRun-IO/qctl/commits/release%2F1.2', gh.call_args_list[1].args[0])
def test_other_source_branch_does_not_change_manifest_default_branch(self):
entry = dict(ENTRY, name='qbit-help', nameWithOwner='QRun-IO/qbit-help')
manifest = {'profile': 'qbit', 'orb_version': VERSION, 'default_branch': 'develop',
'publish': {'snapshot': False, 'release_candidate': False, 'release': False}}
files = {'.qqq-ci.yml': audit.generator.yaml.safe_dump(manifest),
'.circleci/config.yml': audit.generator.yaml.safe_dump(audit.standard.canonical_caller('qbit', VERSION))}
snapshot = Snapshot(files)
snapshot.branch = 'main'
snapshot.default_branch = 'develop'
report = audit.audit(entry, snapshot, VERSION, SHA, POLICY)
self.assertEqual([], report['findings'])
self.assertEqual('main', report['source_branch'])
self.assertEqual('develop', report['default_branch'])
def test_selected_branch_read_failure_is_unknown_not_default_fallback(self):
captured = []
def factory(entry, live):
captured.append(entry)
raise audit.ReadError('branch unavailable')
report = audit.run([ENTRY], VERSION, SHA, {}, live=True,
snapshot_factory=factory, source_branch='main')
self.assertEqual('main', captured[0]['sourceBranch'])
self.assertEqual('unknown', report['results'][0]['status'])
self.assertEqual('main', report['results'][0]['source_branch'])
self.assertNotIn('sourceBranch', ENTRY)
def test_omitted_source_branch_still_reads_repository_default(self):
replies = [{'default_branch': 'develop', 'archived': False}, {'sha': SHA},
{'truncated': False, 'tree': []}]
with patch.object(audit, 'gh', side_effect=replies) as gh:
snapshot = audit.Snapshot(ENTRY, live=True)
self.assertEqual('develop', snapshot.branch)
self.assertEqual('develop', snapshot.default_branch)
self.assertEqual('repos/QRun-IO/qctl/commits/develop', gh.call_args_list[1].args[0])
def test_explicit_source_branch_cannot_relabel_offline_snapshot(self):
with self.assertRaises(ValueError):
audit.run([ENTRY], VERSION, SHA, {}, source_branch='main')
with self.assertRaises(audit.ReadError):
audit.Snapshot(dict(ENTRY, sourceBranch='main'), live=False)
def test_invalid_source_branch_is_rejected_before_api_calls(self):
for branch in ('', 'main?ref=develop', 'main\n', 123):
with self.subTest(branch=branch), patch.object(audit, 'gh') as gh:
with self.assertRaises(audit.ReadError):
audit.Snapshot(dict(ENTRY, sourceBranch=branch), live=True)
gh.assert_not_called()
def native(self, files=None, checks=None, policy=POLICY):
files = files if files is not None else {'.github/workflows/build.yml': audit.qctl.generate(SHA)}
return audit.audit(ENTRY, Snapshot(files, checks), VERSION, SHA, policy)
+58
View File
@@ -0,0 +1,58 @@
import json
import os
from pathlib import Path
import subprocess
import sys
import tempfile
import unittest
import yaml
ROOT = Path(__file__).parents[1]
class BranchLanguages(unittest.TestCase):
def select(self, tracked, untracked=()):
worker = yaml.safe_load((ROOT / '.github/workflows/qbit-codeql.yml').read_text())
script = next(s['run'] for s in worker['jobs']['analyze']['steps'] if s.get('id') == 'languages')
script = script.split("python3 <<'PY'\n", 1)[1].rsplit('\nPY', 1)[0]
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
subprocess.run(['git', 'init', '-q', directory], check=True)
for name in (*tracked, *untracked):
path = root / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text('fixture')
if tracked:
subprocess.run(['git', 'add', '--', *tracked], cwd=root, check=True)
output = root / 'outputs'
result = subprocess.run([sys.executable, '-c', script], cwd=root,
env={**os.environ, 'GITHUB_OUTPUT': str(output)}, capture_output=True, text=True)
return result, output.read_text() if output.exists() else ''
def test_historical_java_branch_does_not_scan_absent_actions(self):
result, output = self.select(['src/Example.java'])
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn('languages=java-kotlin\n', output)
self.assertIn('build-mode=none\n', output)
def test_current_branch_preserves_all_present_supported_languages(self):
result, output = self.select(['src/Example.java', '.github/workflows/ci.yaml', 'web/app.tsx', 'tools/check.py'])
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn('languages=java-kotlin,javascript-typescript,python,actions\n', output)
def test_kotlin_requires_a_build(self):
result, output = self.select(['src/Example.kt', '.github/workflows/ci.yml'])
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn('build-mode=autobuild\n', output)
def test_untracked_files_do_not_select_languages(self):
result, output = self.select(['src/Example.java'], ['web/generated.js', '.github/workflows/untracked.yml'])
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn('languages=java-kotlin\n', output)
def test_placeholder_fails_explicitly(self):
result, output = self.select(['README.md'])
self.assertNotEqual(0, result.returncode)
self.assertIn('No supported source', result.stderr)
if __name__ == '__main__':
unittest.main()
+33 -11
View File
@@ -6,6 +6,8 @@ Example: python tools/audit_estate.py --inventory inventory.json --orb-version 0
Policy: {"profiles":{"qbit":{"required_checks":{"main":["observed context"],
"develop":["observed context"]}}},"repositories":{"QRun-IO/example":{...}}}.
Only use contexts verified on hosted canaries. Absent policy is unknown, not pass.
Use --live --source-branch main (or release/...) to inspect that branch's source;
omitting it retains default-branch auditing. Unavailable branches remain unknown.
A profile/repository policy may set rc_worker_sha independently of --worker-sha
so an RC-only worker change does not require updating unchanged native workers.
"""
@@ -71,11 +73,17 @@ class Snapshot:
raise ReadError('invalid repository name')
self.live = live
self.path = entry.get('localPath', '')
self.branch = (entry.get('defaultBranchRef') or {}).get('name')
requested = entry.get('sourceBranch')
if requested is not None and (not live or not isinstance(requested, str)
or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._/-]*', requested)):
raise ReadError('explicit source branch requires a valid branch name and live lookup')
self.default_branch = (entry.get('defaultBranchRef') or {}).get('name')
self.branch = requested or self.default_branch
self.sha = entry.get('sha', '')
if live:
info = gh('repos/' + self.repo)
self.branch = info['default_branch']
self.default_branch = info['default_branch']
self.branch = requested or self.default_branch
if info['archived']:
raise ReadError('repository is now archived; refresh inventory')
self.sha = gh('repos/' + self.repo + '/commits/' + quote(self.branch, safe=''))['sha']
@@ -169,7 +177,8 @@ def audit(entry, snapshot, version, worker_sha, policy):
name = entry['name']
profile = policy.get('profile') or ('qbit' if name.startswith('qbit-') else PROFILES.get(name))
result = {'repository': entry['nameWithOwner'], 'sha': snapshot.sha,
'default_branch': snapshot.branch, 'profile': profile, 'findings': [], 'required_checks': {}}
'default_branch': getattr(snapshot, 'default_branch', snapshot.branch),
'source_branch': snapshot.branch, 'profile': profile, 'findings': [], 'required_checks': {}}
findings = result['findings']
def finding(code, path=None, detail=None):
findings.append({k: v for k, v in {'code': code, 'path': path, 'detail': detail}.items() if v is not None})
@@ -198,7 +207,7 @@ def audit(entry, snapshot, version, worker_sha, policy):
manifest = Path(directory) / 'manifest.yml'
manifest.write_text(raw, encoding='utf-8')
generator.load_manifest(manifest, pin)
if data.get('default_branch') != snapshot.branch:
if data.get('default_branch') != result['default_branch']:
finding('default_branch_drift', '.qqq-ci.yml')
if caller is not None:
standard.validate(caller, raw, pin)
@@ -224,17 +233,22 @@ def audit(entry, snapshot, version, worker_sha, policy):
if other != path and 'qbit-release-rc.yml@' in snapshot.read(other):
finding('duplicate_rc_bridge', other)
for kind, definition in auxiliary.BRIDGES.items():
if definition['repository'] != entry['nameWithOwner']:
bridge_sha = worker_sha
if kind == 'qbit-codeql':
if profile != 'qbit' or 'codeql_worker_sha' not in policy:
continue
bridge_sha = policy['codeql_worker_sha']
elif definition['repository'] != entry['nameWithOwner']:
continue
path = definition['path']
raw = snapshot.read(path)
if raw is None:
finding('missing_native_maintenance_bridge', path)
continue
if not re.fullmatch(r'[0-9a-f]{40}', worker_sha or ''):
if not re.fullmatch(r'[0-9a-f]{40}', bridge_sha or ''):
finding('native_pin_policy_missing', path)
continue
expected = generator.yaml.safe_dump(auxiliary.canonical(kind, worker_sha), sort_keys=False)
expected = generator.yaml.safe_dump(auxiliary.canonical(kind, bridge_sha), sort_keys=False)
if raw != expected:
finding('native_maintenance_bridge_drift', path)
else:
@@ -324,9 +338,13 @@ def audit(entry, snapshot, version, worker_sha, policy):
return result
def run(entries, version, worker_sha, policies, live=False, snapshot_factory=Snapshot):
def run(entries, version, worker_sha, policies, live=False, snapshot_factory=Snapshot, source_branch=None):
if source_branch is not None and not live:
raise ValueError('Explicit source branch audits require --live')
results = []
for entry in entries:
if source_branch is not None:
entry = dict(entry, sourceBranch=source_branch)
if entry.get('isArchived'):
results.append({'repository': entry['nameWithOwner'], 'status': 'archived_skip'})
continue
@@ -337,10 +355,11 @@ def run(entries, version, worker_sha, policies, live=False, snapshot_factory=Sna
try:
results.append(audit(entry, snapshot_factory(entry, live), version, worker_sha, policy))
except (ReadError, OSError, ValueError, KeyError, subprocess.TimeoutExpired):
results.append({'repository': entry['nameWithOwner'], 'status': 'unknown', 'reason': 'source/API/policy read failed'})
results.append({'repository': entry['nameWithOwner'], 'source_branch': source_branch,
'status': 'unknown', 'reason': 'source/API/policy read failed'})
return {'inventory_count': len(entries), 'active_count': sum(not e.get('isArchived', False) for e in entries),
'covered_count': len(results), 'unique_repository_count': len({e['nameWithOwner'] for e in entries}),
'live': live, 'results': results}
'live': live, 'source_branch_selector': source_branch or 'default', 'results': results}
def main():
@@ -350,12 +369,15 @@ def main():
parser.add_argument('--worker-sha')
parser.add_argument('--policy', type=Path)
parser.add_argument('--live', action='store_true', help='Read current source and branch rules using existing gh authentication')
parser.add_argument('--source-branch', help='Inspect this branch instead of the repository default; requires --live')
parser.add_argument('--expected-active', type=int, default=68)
parser.add_argument('--output', type=Path)
args = parser.parse_args()
if args.source_branch is not None and not args.live:
parser.error('--source-branch requires --live')
entries = json.loads(args.inventory.read_text(encoding='utf-8'))
policies = json.loads(args.policy.read_text(encoding='utf-8')) if args.policy else {}
report = run(entries, args.orb_version, args.worker_sha, policies, args.live)
report = run(entries, args.orb_version, args.worker_sha, policies, args.live, source_branch=args.source_branch)
report['expected_active_count'] = args.expected_active
report['coverage_matches_expected'] = (report['active_count'] == args.expected_active
and report['unique_repository_count'] == report['inventory_count'])