-
Notifications
You must be signed in to change notification settings - Fork 162
docs(troubleshooting): explain the audit-module antivirus false positive - #3348
Open
github-actions[bot] wants to merge 1 commit into
Open
docs(troubleshooting): explain the audit-module antivirus false positive #3348github-actions[bot] wants to merge 1 commit into
github-actions[bot] wants to merge 1 commit into
Conversation
Bitdefender's Generic.PY.SordealStealer heuristic fires on the bytecode cache of gaia/skills/audit/code.py, whose rule tables necessarily name the credential paths and decoder calls an infostealer targets. Add a troubleshooting section that identifies the detection as a false positive, gives users a RECORD-based integrity check they can run themselves, and separates 'add an exclusion' from 'you were actually tampered with'. Closes #3347
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A user's antivirus quarantined a file inside their GAIA install and told them GAIA was an infostealer, with nothing in our docs to say otherwise — a genuinely alarming experience with no way to self-check. It was a false positive on GAIA's own skill auditor: that module has to name the things a credential stealer targets (
~/.ssh,.aws/credentials, browser cookie stores,base64.b64decode) in order to detect them, so its compiled bytecode reads like the thing it catches. Anyone who hits this now finds a troubleshooting section that names the false positive, gives them a one-line integrity check that proves their install is byte-identical to the published wheel, and — importantly — tells them when not to add an exclusion because something really was modified.No source change: the flagged artifact is a local bytecode cache, the wheel ships no
__pycache__, and the reporter verified the source file matches its published hash. Rewriting the detector's vocabulary to dodge a proprietary heuristic would be unverifiable and would weaken the auditor.Closes #3347
Test plan
python util/lint.py --allshows no new failures (the one Import Validation error reproduces on a cleanmain)#av-false-positiveanchor resolves from the "Antivirus interference" cross-linkmodified files: none:~/.gaia/venv/bin/python -c "import base64,csv,hashlib,pathlib,sysconfig; ..."(copy from the doc)%USERPROFILE%\.gaia\venv\Scripts\python.exe🔍 Technical details
Root cause.
src/gaia/skills/audit/code.pyis the AST analyser behind the skill-audit gate. Its rule tables are the trigger:_CREDENTIAL_PATTERNS(code.py:543-557) —\.ssh/,id_rsa,\.aws/credentials,\.netrc,\.git-credentials,Login Data|Cookies|key4\.db|logins\.json_DECODERS(code.py:565-583) —base64.b64decode,zlib.decompress,binascii.unhexlify, ..._BUILTIN_SINKS(code.py:519) —eval,exec,compile,__import__Compiled into one
.pyc, that is an infostealer's target list plus its unpacking primitives.Generic.PY.SordealStealeris a Python-bytecode heuristic matching the detector's own vocabulary.The reported path ended in
.pyc.2586770202400— CPython's_write_atomictemp name (<pyc>.<id(path)>), written locally on first import.setup.pyshipsgaia.skills.auditas source only; no__pycache__is in the wheel, so the flagged file was never downloaded.Change. One new section in
docs/reference/install-troubleshooting.mdx(anchor#av-false-positive), plus a one-line pointer to it from the existing "Antivirus interference" subsection, which covers a different symptom (install hangs) and was the wrong landing spot.Verification of the doc's integrity command. The one-liner walks the
RECORDmanifest and recomputes each file's unpadded urlsafe-base64 SHA-256. Exercised verbatim two ways: against a real installed dist-info (printsmodified files: none), and against a synthetic dist-info whose file was then edited (printsmodified files: ['gaia/code.py']) — so it detects tampering rather than always passing.Validation limits. Docs-only, no Python touched.
util/lint.py --allPython checks pass (black, isort, pylint, flake8, bandit); the single Import Validation error reproduces with the change stashed, so it is pre-existing. The unit suite could not run in this environment —gaiais not installed here, so all 340 collections error onModuleNotFoundError: No module named 'gaia'on a clean tree as well.Deliberately not done. Restructuring the rule tables into a data file to keep those strings out of the bytecode. It would be a refactor of a security-gate module, chasing a closed-source heuristic with no way to confirm the result. The durable fix is a vendor false-positive submission.