pre-commit-bigfix 2.1.1__tar.gz → 2.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. {pre_commit_bigfix-2.1.1/pre_commit_bigfix.egg-info → pre_commit_bigfix-2.3.0}/PKG-INFO +119 -8
  2. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/README.md +117 -6
  3. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/__init__.py +1 -1
  4. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_common.py +10 -0
  5. pre_commit_bigfix-2.3.0/pre_commit_bigfix/bes_content_score_risk.py +1376 -0
  6. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_conventions_check.py +31 -1
  7. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_relevance_lint.py +214 -43
  8. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/run_all.py +7 -1
  9. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0/pre_commit_bigfix.egg-info}/PKG-INFO +119 -8
  10. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix.egg-info/SOURCES.txt +3 -0
  11. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix.egg-info/entry_points.txt +1 -0
  12. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix.egg-info/requires.txt +1 -1
  13. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/setup.cfg +2 -1
  14. pre_commit_bigfix-2.3.0/tests/test_bes_content_score_risk.py +884 -0
  15. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_conventions_check.py +67 -0
  16. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_relevance_lint.py +246 -14
  17. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_hook_declarations.py +10 -0
  18. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_schema_guard.py +94 -0
  19. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/LICENSE +0 -0
  20. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/MANIFEST.in +0 -0
  21. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_actionscript_lint_schclass.py +0 -0
  22. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_actionscript_validate_prefetch.py +0 -0
  23. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_actionscript_validate_script.py +0 -0
  24. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_relevance_convert_group.py +0 -0
  25. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_schema_validate.py +0 -0
  26. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/bes_siterepo_validate_layout.py +0 -0
  27. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/schclass.py +0 -0
  28. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/schclass_data/ExpandedActionScript.schclass +0 -0
  29. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/schclass_data/bigfix_overrides.schclass +0 -0
  30. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix/schclass_tokenizer.py +0 -0
  31. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix.egg-info/dependency_links.txt +0 -0
  32. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pre_commit_bigfix.egg-info/top_level.txt +0 -0
  33. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/pyproject.toml +0 -0
  34. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/setup.py +0 -0
  35. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_actionscript_lint_schclass.py +0 -0
  36. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_actionscript_validate_prefetch.py +0 -0
  37. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_actionscript_validate_script.py +0 -0
  38. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_common.py +0 -0
  39. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_relevance_convert_group.py +0 -0
  40. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_schema_validate.py +0 -0
  41. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_bes_siterepo_validate_layout.py +0 -0
  42. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_package_metadata.py +0 -0
  43. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_release_workflow.py +0 -0
  44. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_run_all.py +0 -0
  45. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_schclass.py +0 -0
  46. {pre_commit_bigfix-2.1.1 → pre_commit_bigfix-2.3.0}/tests/test_schclass_tokenizer.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pre-commit-bigfix
3
- Version: 2.1.1
3
+ Version: 2.3.0
4
4
  Summary: pre-commit hooks for BigFix content
5
5
  Home-page: https://github.com/jgstew/pre-commit-bigfix
6
6
  Author: JGStew
@@ -25,7 +25,7 @@ License-File: LICENSE
25
25
  Requires-Dist: bigfix_prefetch>=1.1.5
26
26
  Requires-Dist: lxml
27
27
  Requires-Dist: validate_bes_xml<3,>=2.4.1
28
- Requires-Dist: bigfix-relevance-analyzer<2,>=1.23.1; python_version >= "3.11"
28
+ Requires-Dist: bigfix-relevance-analyzer<2,>=1.26.0; python_version >= "3.11"
29
29
  Provides-Extra: test
30
30
  Requires-Dist: pytest; extra == "test"
31
31
  Dynamic: license-file
@@ -52,6 +52,7 @@ repos:
52
52
  - id: bes-actionscript-validate-script
53
53
  - id: bes-relevance-lint
54
54
  - id: bes-relevance-convert-group
55
+ - id: bes-content-score-risk
55
56
  # only in a Git External Custom Site (repository site) repo:
56
57
  - id: bes-siterepo-validate-layout
57
58
  ```
@@ -176,7 +177,8 @@ action-ui-metadata / CPE-2.3 / CVENames / x-relevance-evaluation-period,
176
177
  prefetch-line shape (URL schemes overridable with `--prefetch-url-schemes`)
177
178
  and https URLs, CDATA usage, blank-line and
178
179
  trailing-whitespace spacing, empty ActionScript, dynamic download statements,
179
- a UTF-8 XML declaration, Title placeholders / whitespace / TODO markers,
180
+ a UTF-8 XML declaration, no DTD (`<!DOCTYPE ...>`, `E223`: the BigFix Console
181
+ refuses to import a file that has one), Title placeholders / whitespace / TODO markers,
180
182
  non-trivial non-empty Relevance with no stray whitespace, unique MIMEField
181
183
  names, unique Analysis Property names/IDs, unique Action IDs, action link text
182
184
  free of empty-substitution gaps, SuccessCriteria body/Option consistency, a
@@ -622,6 +624,7 @@ of the file.
622
624
  | `E612` | an ActionScript `{` with anything after it on its line and no `}` to close it there, which fails the action |
623
625
  | `E613` | a `<?Relevance` with no closing `?>`, so its relevance was not linted |
624
626
  | `E614` | a BES file that is not well-formed XML, so nothing in it was linted (**off by default**; `--enable E614`) |
627
+ | `E615` | an `--auto-fix` was not written because it would turn a BES.xsd-valid file invalid; fix by hand, or `--disable E615` to write it anyway |
625
628
  | `W600` | a name no inspector dump defines |
626
629
  | `W601` | a property written singular over an object that may be plural |
627
630
  | `W602` | a singular spelling mid-chain (under a `whose` filter, or where a plural is built from it), where the plural reads safer |
@@ -633,7 +636,7 @@ of the file.
633
636
 
634
637
  `W600` is a warning rather than an error because a repo running a newer client
635
638
  than the analyzer's dump snapshot legitimately uses names it has never heard
636
- of. `W601` is **disabled by default** in the hook declaration: across 1,108
639
+ of. `W601` is **disabled by default**: across 1,108
637
640
  `.bes` files of real content it fires 6,127 times, which drowns everything
638
641
  else. Switch it back on with `--enable W601`.
639
642
 
@@ -644,12 +647,35 @@ says the relevance that could be extracted is sound, not that the file parses.
644
647
  A file opts out of every check here with
645
648
  `<!-- pre-commit-skip: bes-relevance-lint -->` anywhere in it. There is no
646
649
  per-rule marker: `--disable` takes a code repo-wide, and a single file that
647
- legitimately needs relevance this complex is what `--max-score` is for. Files
648
- are never rewritten, but where the analyzer can work out a safe rewrite of a
649
- whole statement (today, the singular spellings behind `W602`) the fixed
650
- statement is printed once under its first finding as `suggested fix: ...`.
650
+ legitimately needs relevance this complex is what `--max-score` is for.
651
651
  E-codes fail the hook; pass `--strict` to also fail on warnings.
652
652
 
653
+ Where the analyzer can work out a safe rewrite of a statement (the singular
654
+ spellings behind `W602`, and the `unique value of` / singular-aggregate
655
+ rewrites behind `E611`), the fixed statement is printed once under its first
656
+ finding as `suggested fix: ...`. By default that is all: **unlike the sibling
657
+ hooks, this one never rewrites a file unless the repo opts in**, because a
658
+ relevance fix changes what a statement says, not just how it is formatted:
659
+
660
+ ```yaml
661
+ - id: bes-relevance-lint
662
+ args: [--auto-fix=yes]
663
+ ```
664
+
665
+ With `--auto-fix=yes`, each safe fix is written in place as the smallest
666
+ edit that makes it (`setting` gains an `s`; a wrap inserts
667
+ `unique value of `), so entities, CDATA and line endings around it are kept.
668
+ The analyzer refuses a fix it cannot prove safe - one that would add a finding
669
+ (a wrap that pushes a statement over `--max-score`, say), or one under a rule
670
+ you `--disable` - and refuses site by site, so a file can come back partly
671
+ fixed. Each written edit is reported as
672
+ `path:line: [W602] auto-fixed: setting -> settings (plural-preferred)`; a fix
673
+ that was not written keeps its `suggested fix:` line with
674
+ `(not auto-fixed: <reason>)`. A fix that would turn a BES.xsd-valid file
675
+ invalid is not written, and is reported as `E615`; files no schema applies to
676
+ (`.rel`, `.bsr`, ...) are written unchecked, as every sibling hook does. Any
677
+ auto-fix fails the hook so the change is reviewed and re-staged.
678
+
653
679
  This hook needs **Python 3.11 or newer** - the analyzer requires it, while the
654
680
  rest of this package still runs on 3.8. No specific interpreter is pinned, since
655
681
  `language_version` names an exact executable and pinning `python3.11` would
@@ -701,6 +727,91 @@ rewrite shows up for review; `--check` only reports. With no files given it
701
727
  checks every `*.bes` below the current folder and never rewrites. A file opts
702
728
  out with `<!-- pre-commit-skip: bes-relevance-convert-group -->`.
703
729
 
730
+ ### bes-content-score-risk
731
+
732
+ Scores how risky a BES file's content is and lists the reasons, so content
733
+ that needs a careful human review is flagged before it is trusted. It is a
734
+ triage signal, not a verdict, and it never changes a file. Each finding adds
735
+ points; a file at or over `--fail-score` (default 50, the HIGH band) fails
736
+ with `E900`.
737
+
738
+ | code | points | signal |
739
+ | --- | --- | --- |
740
+ | `W901` | 20 | script in a Description: `<script>`, `javascript:`, an `on*=` handler |
741
+ | `W902` | 25 | session relevance in a Description: `<?relevance ...?>`, `EvaluateRelevance(` |
742
+ | `W903` | 15 | both in one Description |
743
+ | `W910` | 25 | ActionScript `download` / `download now`: not hashed. A later `continue if {sha1 of ...}` does not excuse it; use a prefetch |
744
+ | `W911` | 25 | `add nohash prefetch item` |
745
+ | `W912` | 10 | a download or prefetch URL over plain `http://` or to a raw IP |
746
+ | `W913` | 15 | a download command in script content (`curl`, `wget`, `Invoke-WebRequest`, `DownloadString`, `bitsadmin`, ...) |
747
+ | `W920` | 2 | base64 that really is an image of its `data:image/` type |
748
+ | `W921` | 20 | base64 (80+ characters) anywhere else |
749
+ | `W922` | 25 | a decoded payload is an executable or a script |
750
+ | `W923` | 20 | a decode or dynamic-run command: `certutil -decode`, `base64 -d`, `FromBase64String`, `powershell -EncodedCommand`, `Invoke-Expression` / `iex`, PsExec, `curl ... \| sh` |
751
+ | `W924` | 15 | other obfuscation: `\x`, `\u`, `%XX` or hex runs decoding to ASCII; `eval(`, `unescape(`, `atob(`, `Function(`, `fromCharCode(` |
752
+ | `W925` | 15 | a decoded payload is gzip, zlib or zip compressed |
753
+ | `W926` | 30 | base64 labelled `data:image/` whose bytes are not that image |
754
+ | `W927` | 10 + inner | a decoded payload holds findings of its own; names the decode path (`base64->gzip->text`) |
755
+ | `W928` | 15 | decoding stopped: 4 MB were decoded, so later payloads were only checked for an executable header |
756
+ | `W929` | 20 | a DTD in the prolog, once per file: its entities are not expanded, and the BigFix Console refuses the file (`bes-conventions-check` `E223`). A DOCTYPE an action writes out, such as a plist's, does not count |
757
+ | `W930` | 25 | a hardcoded secret: `password=`, `token=`, `api_key:` and the like with a literal value (not a `{parameter}`, `$var` or `%VAR%`), a private key, an AWS access key ID. The value is never printed |
758
+ | `W931` | 20 | a command that weakens security: disables UAC, Defender, a firewall, SELinux, Gatekeeper or SIP; deletes shadow copies or clears event logs; adds a user or an administrator; edits `sudoers` or `authorized_keys` |
759
+ | `W932` | 30 | a Description that loads remote content or reaches outside the page: `<script src>` / `<iframe src>` to a URL, `ActiveXObject`, `WScript.Shell`, `XMLHttpRequest`, `fetch(`, `document.cookie` |
760
+ | `W940` | 30 | tampers with the BigFix client: stops, disables or uninstalls BESClient, deletes `__BESData`, replaces `masthead`/`ActionSite.afxm` |
761
+ | `W941` | 25 | redirects the client to another relay or server (`__RelayServer1/2`, `_BESClient_RelaySelect_*`, ParentRelay, affiliation) |
762
+ | `W942` | 10 | uploads endpoint files to the root server (`archive now`, `_BESClient_ArchiveManager_*`, `_BESClient_UploadManager_*`); the destination cannot be redirected, but the files become readable on the server |
763
+ | `W943` | 25 | calls the BigFix REST API (`/api/actions`, ...): content that can create more content or actions |
764
+ | `W944` | 30 | an action that targets all computers (`<AllComputers>true`) |
765
+ | `W945` | 20 | runs a command taken from a client setting or a file (`wait {value of setting ...}`) |
766
+ | `W946` | 30 | compares `now` to a fixed date in relevance or an action (a time bomb?) |
767
+ | `W947` | 15 | relevance or an action pinned to one host name, IP or MAC |
768
+ | `W948` | 5 | a `{parameter}` placed straight into a command line (command injection?) |
769
+ | `W949` | 20 | uploads files (W942) and reads a credential store (W950) in one file: secrets may end up on the server |
770
+ | `W950` | 30 | reads a credential store: `/etc/shadow`, the SAM or SECURITY hive, SSH keys, browser logins, keychains, `.aws/credentials`, `NTDS.dit`, lsass; in ActionScript, Relevance or an Analysis Property |
771
+ | `W951` | 30 | dumps credentials or prompts for a password: mimikatz, procdump of lsass, `reg save HKLM\SAM`, `Get-Credential`, an AppleScript `with hidden answer` dialog |
772
+ | `W952` | 25 | weakens credential protection: WDigest `UseLogonCredential=1`, `RunAsPPL=0`, `NoLMHash=0` |
773
+ | `W953` | 25 | sends data off the endpoint: `curl -d/-F/-T`, an `Invoke-WebRequest`/`Invoke-RestMethod` POST or PUT, `scp`, `sftp`, `ftp`, `UploadFile` |
774
+ | `W954` | 20 | a URL on a paste site, URL shortener, tunnel (ngrok, trycloudflare), raw.githubusercontent/gist, the Discord CDN, or dynamic DNS |
775
+ | `W955` | 25 | a URL with credentials in it (`https://user:pass@...`) |
776
+ | `W956` | 25 | turns off TLS or host-key verification: `curl -k`, `--no-check-certificate`, `ServerCertificateValidationCallback`, `StrictHostKeyChecking no` |
777
+ | `W957` | 30 | adds a trusted root CA (`certutil -addstore root`, `add-trusted-cert`, `update-ca-certificates`) |
778
+ | `W958` | 20 | changes hosts, DNS or proxy settings |
779
+ | `W959` | 20 | enables remote access: RDP, WinRM, SSH root or password login, SMBv1, the guest account, `LocalAccountTokenFilterPolicy=1` |
780
+ | `W960` | 30 | bypasses AMSI or ETW, loads code reflectively, or compiles it at run time (`Add-Type -TypeDefinition`, `csc.exe`, an MSBuild project, `VirtualAlloc`) |
781
+ | `W961` | 20 | a built-in binary used to run code: `mshta`, `regsvr32 /i:`, `rundll32 javascript:`, `wmic process call create`, `odbcconf`, `forfiles /c`, `cmstp` |
782
+ | `W962` | 20 | keyword obfuscation: PowerShell backticks or cmd carets inside a word, env-var substrings other than `%DATE%`/`%TIME%`, split-and-joined strings, `-bxor`, string reversal |
783
+ | `W963` | 30 | a bidi or zero-width character, which can hide code (a byte-order mark opening the file is fine) |
784
+ | `W964` | 20 | stops or removes a security tool: Defender, an EDR agent, Sysmon, Tanium, osquery, auditd |
785
+ | `W965` | 15 | hides or backdates files (`attrib +h +s`, `touch -t`, `SetFileTime`) |
786
+ | `W966` | 25 | loads a kernel driver or module (`insmod`, `kextload`), or turns on test signing |
787
+ | `W967` | 15 | setuid or world-writable permissions, `Everyone:F` |
788
+ | `W968` | 20 | an offensive, recon or mining tool: nmap, responder, BloodHound, impacket, xmrig, `stratum+tcp` |
789
+ | `W970` | 25 | stealthy persistence: IFEO `Debugger`, sticky-keys replacement, WMI event subscriptions, Winlogon `Userinit`/`Shell`, `AppInit_DLLs`, `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, shell rc and `profile.d` files |
790
+ | `W971` | 10 | ordinary persistence: a Run key, service, launchd or systemd unit, scheduled task or cron job |
791
+ | `W972` | 30 | a destructive disk operation: `diskpart`, `format`, `dd of=/dev/...`, `mkfs`, `shred`, `cipher /w`, `rm -rf /` |
792
+ | `W973` | 20 | SQL that changes data (`DROP`, `DELETE`, `UPDATE`, `TRUNCATE`, `ALTER`), or `xp_cmdshell` |
793
+ | `W980` | 20 | a password field in a Description: credentials collected in the console |
794
+ | `W981` | 30 | a UNC (`\\server\share`) or `file:` link or image in a Description; rendering it may send the operator's NTLM hash |
795
+ | `W982` | 15 | a remote image or media file in a Description: a beacon on whoever opens it |
796
+ | `W983` | 25 | a `<meta refresh>`, `<base href>`, or a `<form action>` posting to another site, in a Description |
797
+ | `W984` | 10 | a hidden element (`display:none`, `visibility:hidden`) in a Description |
798
+ | `W990` | 10 | a `createfile` payload longer than 200 lines: hard to review |
799
+ | `W991` | 15 | a Task or Fixlet titled like a check (Check, Get, Report, Inventory, ...) whose action changes state |
800
+ | `W900` | | a MEDIUM score (25-49) |
801
+ | `W908` | | not parseable XML; skipped |
802
+ | `E900` | | the score is at or over `--fail-score` |
803
+
804
+ Every encoded blob is decoded and scanned again: base64 as UTF-8 and as
805
+ UTF-16LE (PowerShell `-EncodedCommand`), compressed data decompressed, up to
806
+ 3 layers and 4 MB per file. `--weight CODE=N` changes a signal's points,
807
+ `--disable CODES` skips signals, and `--fail-score N` moves the threshold.
808
+ The default weights are a starting point, to be tuned against real content.
809
+
810
+ The signals favor recall over precision: it is better to flag something a
811
+ reviewer then accepts than to miss something malicious. Content written by
812
+ `createfile` is scanned like any other script content, so a configuration
813
+ file that only lists tool names (a Sysmon config, say) can still score.
814
+
704
815
  ### bes-siterepo-validate-layout
705
816
 
706
817
  For a BigFix [Git External Custom Site](https://help.hcl-software.com/bigfix/11.0/platform/Platform/Config/c_repository_site_git.html)
@@ -20,6 +20,7 @@ repos:
20
20
  - id: bes-actionscript-validate-script
21
21
  - id: bes-relevance-lint
22
22
  - id: bes-relevance-convert-group
23
+ - id: bes-content-score-risk
23
24
  # only in a Git External Custom Site (repository site) repo:
24
25
  - id: bes-siterepo-validate-layout
25
26
  ```
@@ -144,7 +145,8 @@ action-ui-metadata / CPE-2.3 / CVENames / x-relevance-evaluation-period,
144
145
  prefetch-line shape (URL schemes overridable with `--prefetch-url-schemes`)
145
146
  and https URLs, CDATA usage, blank-line and
146
147
  trailing-whitespace spacing, empty ActionScript, dynamic download statements,
147
- a UTF-8 XML declaration, Title placeholders / whitespace / TODO markers,
148
+ a UTF-8 XML declaration, no DTD (`<!DOCTYPE ...>`, `E223`: the BigFix Console
149
+ refuses to import a file that has one), Title placeholders / whitespace / TODO markers,
148
150
  non-trivial non-empty Relevance with no stray whitespace, unique MIMEField
149
151
  names, unique Analysis Property names/IDs, unique Action IDs, action link text
150
152
  free of empty-substitution gaps, SuccessCriteria body/Option consistency, a
@@ -590,6 +592,7 @@ of the file.
590
592
  | `E612` | an ActionScript `{` with anything after it on its line and no `}` to close it there, which fails the action |
591
593
  | `E613` | a `<?Relevance` with no closing `?>`, so its relevance was not linted |
592
594
  | `E614` | a BES file that is not well-formed XML, so nothing in it was linted (**off by default**; `--enable E614`) |
595
+ | `E615` | an `--auto-fix` was not written because it would turn a BES.xsd-valid file invalid; fix by hand, or `--disable E615` to write it anyway |
593
596
  | `W600` | a name no inspector dump defines |
594
597
  | `W601` | a property written singular over an object that may be plural |
595
598
  | `W602` | a singular spelling mid-chain (under a `whose` filter, or where a plural is built from it), where the plural reads safer |
@@ -601,7 +604,7 @@ of the file.
601
604
 
602
605
  `W600` is a warning rather than an error because a repo running a newer client
603
606
  than the analyzer's dump snapshot legitimately uses names it has never heard
604
- of. `W601` is **disabled by default** in the hook declaration: across 1,108
607
+ of. `W601` is **disabled by default**: across 1,108
605
608
  `.bes` files of real content it fires 6,127 times, which drowns everything
606
609
  else. Switch it back on with `--enable W601`.
607
610
 
@@ -612,12 +615,35 @@ says the relevance that could be extracted is sound, not that the file parses.
612
615
  A file opts out of every check here with
613
616
  `<!-- pre-commit-skip: bes-relevance-lint -->` anywhere in it. There is no
614
617
  per-rule marker: `--disable` takes a code repo-wide, and a single file that
615
- legitimately needs relevance this complex is what `--max-score` is for. Files
616
- are never rewritten, but where the analyzer can work out a safe rewrite of a
617
- whole statement (today, the singular spellings behind `W602`) the fixed
618
- statement is printed once under its first finding as `suggested fix: ...`.
618
+ legitimately needs relevance this complex is what `--max-score` is for.
619
619
  E-codes fail the hook; pass `--strict` to also fail on warnings.
620
620
 
621
+ Where the analyzer can work out a safe rewrite of a statement (the singular
622
+ spellings behind `W602`, and the `unique value of` / singular-aggregate
623
+ rewrites behind `E611`), the fixed statement is printed once under its first
624
+ finding as `suggested fix: ...`. By default that is all: **unlike the sibling
625
+ hooks, this one never rewrites a file unless the repo opts in**, because a
626
+ relevance fix changes what a statement says, not just how it is formatted:
627
+
628
+ ```yaml
629
+ - id: bes-relevance-lint
630
+ args: [--auto-fix=yes]
631
+ ```
632
+
633
+ With `--auto-fix=yes`, each safe fix is written in place as the smallest
634
+ edit that makes it (`setting` gains an `s`; a wrap inserts
635
+ `unique value of `), so entities, CDATA and line endings around it are kept.
636
+ The analyzer refuses a fix it cannot prove safe - one that would add a finding
637
+ (a wrap that pushes a statement over `--max-score`, say), or one under a rule
638
+ you `--disable` - and refuses site by site, so a file can come back partly
639
+ fixed. Each written edit is reported as
640
+ `path:line: [W602] auto-fixed: setting -> settings (plural-preferred)`; a fix
641
+ that was not written keeps its `suggested fix:` line with
642
+ `(not auto-fixed: <reason>)`. A fix that would turn a BES.xsd-valid file
643
+ invalid is not written, and is reported as `E615`; files no schema applies to
644
+ (`.rel`, `.bsr`, ...) are written unchecked, as every sibling hook does. Any
645
+ auto-fix fails the hook so the change is reviewed and re-staged.
646
+
621
647
  This hook needs **Python 3.11 or newer** - the analyzer requires it, while the
622
648
  rest of this package still runs on 3.8. No specific interpreter is pinned, since
623
649
  `language_version` names an exact executable and pinning `python3.11` would
@@ -669,6 +695,91 @@ rewrite shows up for review; `--check` only reports. With no files given it
669
695
  checks every `*.bes` below the current folder and never rewrites. A file opts
670
696
  out with `<!-- pre-commit-skip: bes-relevance-convert-group -->`.
671
697
 
698
+ ### bes-content-score-risk
699
+
700
+ Scores how risky a BES file's content is and lists the reasons, so content
701
+ that needs a careful human review is flagged before it is trusted. It is a
702
+ triage signal, not a verdict, and it never changes a file. Each finding adds
703
+ points; a file at or over `--fail-score` (default 50, the HIGH band) fails
704
+ with `E900`.
705
+
706
+ | code | points | signal |
707
+ | --- | --- | --- |
708
+ | `W901` | 20 | script in a Description: `<script>`, `javascript:`, an `on*=` handler |
709
+ | `W902` | 25 | session relevance in a Description: `<?relevance ...?>`, `EvaluateRelevance(` |
710
+ | `W903` | 15 | both in one Description |
711
+ | `W910` | 25 | ActionScript `download` / `download now`: not hashed. A later `continue if {sha1 of ...}` does not excuse it; use a prefetch |
712
+ | `W911` | 25 | `add nohash prefetch item` |
713
+ | `W912` | 10 | a download or prefetch URL over plain `http://` or to a raw IP |
714
+ | `W913` | 15 | a download command in script content (`curl`, `wget`, `Invoke-WebRequest`, `DownloadString`, `bitsadmin`, ...) |
715
+ | `W920` | 2 | base64 that really is an image of its `data:image/` type |
716
+ | `W921` | 20 | base64 (80+ characters) anywhere else |
717
+ | `W922` | 25 | a decoded payload is an executable or a script |
718
+ | `W923` | 20 | a decode or dynamic-run command: `certutil -decode`, `base64 -d`, `FromBase64String`, `powershell -EncodedCommand`, `Invoke-Expression` / `iex`, PsExec, `curl ... \| sh` |
719
+ | `W924` | 15 | other obfuscation: `\x`, `\u`, `%XX` or hex runs decoding to ASCII; `eval(`, `unescape(`, `atob(`, `Function(`, `fromCharCode(` |
720
+ | `W925` | 15 | a decoded payload is gzip, zlib or zip compressed |
721
+ | `W926` | 30 | base64 labelled `data:image/` whose bytes are not that image |
722
+ | `W927` | 10 + inner | a decoded payload holds findings of its own; names the decode path (`base64->gzip->text`) |
723
+ | `W928` | 15 | decoding stopped: 4 MB were decoded, so later payloads were only checked for an executable header |
724
+ | `W929` | 20 | a DTD in the prolog, once per file: its entities are not expanded, and the BigFix Console refuses the file (`bes-conventions-check` `E223`). A DOCTYPE an action writes out, such as a plist's, does not count |
725
+ | `W930` | 25 | a hardcoded secret: `password=`, `token=`, `api_key:` and the like with a literal value (not a `{parameter}`, `$var` or `%VAR%`), a private key, an AWS access key ID. The value is never printed |
726
+ | `W931` | 20 | a command that weakens security: disables UAC, Defender, a firewall, SELinux, Gatekeeper or SIP; deletes shadow copies or clears event logs; adds a user or an administrator; edits `sudoers` or `authorized_keys` |
727
+ | `W932` | 30 | a Description that loads remote content or reaches outside the page: `<script src>` / `<iframe src>` to a URL, `ActiveXObject`, `WScript.Shell`, `XMLHttpRequest`, `fetch(`, `document.cookie` |
728
+ | `W940` | 30 | tampers with the BigFix client: stops, disables or uninstalls BESClient, deletes `__BESData`, replaces `masthead`/`ActionSite.afxm` |
729
+ | `W941` | 25 | redirects the client to another relay or server (`__RelayServer1/2`, `_BESClient_RelaySelect_*`, ParentRelay, affiliation) |
730
+ | `W942` | 10 | uploads endpoint files to the root server (`archive now`, `_BESClient_ArchiveManager_*`, `_BESClient_UploadManager_*`); the destination cannot be redirected, but the files become readable on the server |
731
+ | `W943` | 25 | calls the BigFix REST API (`/api/actions`, ...): content that can create more content or actions |
732
+ | `W944` | 30 | an action that targets all computers (`<AllComputers>true`) |
733
+ | `W945` | 20 | runs a command taken from a client setting or a file (`wait {value of setting ...}`) |
734
+ | `W946` | 30 | compares `now` to a fixed date in relevance or an action (a time bomb?) |
735
+ | `W947` | 15 | relevance or an action pinned to one host name, IP or MAC |
736
+ | `W948` | 5 | a `{parameter}` placed straight into a command line (command injection?) |
737
+ | `W949` | 20 | uploads files (W942) and reads a credential store (W950) in one file: secrets may end up on the server |
738
+ | `W950` | 30 | reads a credential store: `/etc/shadow`, the SAM or SECURITY hive, SSH keys, browser logins, keychains, `.aws/credentials`, `NTDS.dit`, lsass; in ActionScript, Relevance or an Analysis Property |
739
+ | `W951` | 30 | dumps credentials or prompts for a password: mimikatz, procdump of lsass, `reg save HKLM\SAM`, `Get-Credential`, an AppleScript `with hidden answer` dialog |
740
+ | `W952` | 25 | weakens credential protection: WDigest `UseLogonCredential=1`, `RunAsPPL=0`, `NoLMHash=0` |
741
+ | `W953` | 25 | sends data off the endpoint: `curl -d/-F/-T`, an `Invoke-WebRequest`/`Invoke-RestMethod` POST or PUT, `scp`, `sftp`, `ftp`, `UploadFile` |
742
+ | `W954` | 20 | a URL on a paste site, URL shortener, tunnel (ngrok, trycloudflare), raw.githubusercontent/gist, the Discord CDN, or dynamic DNS |
743
+ | `W955` | 25 | a URL with credentials in it (`https://user:pass@...`) |
744
+ | `W956` | 25 | turns off TLS or host-key verification: `curl -k`, `--no-check-certificate`, `ServerCertificateValidationCallback`, `StrictHostKeyChecking no` |
745
+ | `W957` | 30 | adds a trusted root CA (`certutil -addstore root`, `add-trusted-cert`, `update-ca-certificates`) |
746
+ | `W958` | 20 | changes hosts, DNS or proxy settings |
747
+ | `W959` | 20 | enables remote access: RDP, WinRM, SSH root or password login, SMBv1, the guest account, `LocalAccountTokenFilterPolicy=1` |
748
+ | `W960` | 30 | bypasses AMSI or ETW, loads code reflectively, or compiles it at run time (`Add-Type -TypeDefinition`, `csc.exe`, an MSBuild project, `VirtualAlloc`) |
749
+ | `W961` | 20 | a built-in binary used to run code: `mshta`, `regsvr32 /i:`, `rundll32 javascript:`, `wmic process call create`, `odbcconf`, `forfiles /c`, `cmstp` |
750
+ | `W962` | 20 | keyword obfuscation: PowerShell backticks or cmd carets inside a word, env-var substrings other than `%DATE%`/`%TIME%`, split-and-joined strings, `-bxor`, string reversal |
751
+ | `W963` | 30 | a bidi or zero-width character, which can hide code (a byte-order mark opening the file is fine) |
752
+ | `W964` | 20 | stops or removes a security tool: Defender, an EDR agent, Sysmon, Tanium, osquery, auditd |
753
+ | `W965` | 15 | hides or backdates files (`attrib +h +s`, `touch -t`, `SetFileTime`) |
754
+ | `W966` | 25 | loads a kernel driver or module (`insmod`, `kextload`), or turns on test signing |
755
+ | `W967` | 15 | setuid or world-writable permissions, `Everyone:F` |
756
+ | `W968` | 20 | an offensive, recon or mining tool: nmap, responder, BloodHound, impacket, xmrig, `stratum+tcp` |
757
+ | `W970` | 25 | stealthy persistence: IFEO `Debugger`, sticky-keys replacement, WMI event subscriptions, Winlogon `Userinit`/`Shell`, `AppInit_DLLs`, `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, shell rc and `profile.d` files |
758
+ | `W971` | 10 | ordinary persistence: a Run key, service, launchd or systemd unit, scheduled task or cron job |
759
+ | `W972` | 30 | a destructive disk operation: `diskpart`, `format`, `dd of=/dev/...`, `mkfs`, `shred`, `cipher /w`, `rm -rf /` |
760
+ | `W973` | 20 | SQL that changes data (`DROP`, `DELETE`, `UPDATE`, `TRUNCATE`, `ALTER`), or `xp_cmdshell` |
761
+ | `W980` | 20 | a password field in a Description: credentials collected in the console |
762
+ | `W981` | 30 | a UNC (`\\server\share`) or `file:` link or image in a Description; rendering it may send the operator's NTLM hash |
763
+ | `W982` | 15 | a remote image or media file in a Description: a beacon on whoever opens it |
764
+ | `W983` | 25 | a `<meta refresh>`, `<base href>`, or a `<form action>` posting to another site, in a Description |
765
+ | `W984` | 10 | a hidden element (`display:none`, `visibility:hidden`) in a Description |
766
+ | `W990` | 10 | a `createfile` payload longer than 200 lines: hard to review |
767
+ | `W991` | 15 | a Task or Fixlet titled like a check (Check, Get, Report, Inventory, ...) whose action changes state |
768
+ | `W900` | | a MEDIUM score (25-49) |
769
+ | `W908` | | not parseable XML; skipped |
770
+ | `E900` | | the score is at or over `--fail-score` |
771
+
772
+ Every encoded blob is decoded and scanned again: base64 as UTF-8 and as
773
+ UTF-16LE (PowerShell `-EncodedCommand`), compressed data decompressed, up to
774
+ 3 layers and 4 MB per file. `--weight CODE=N` changes a signal's points,
775
+ `--disable CODES` skips signals, and `--fail-score N` moves the threshold.
776
+ The default weights are a starting point, to be tuned against real content.
777
+
778
+ The signals favor recall over precision: it is better to flag something a
779
+ reviewer then accepts than to miss something malicious. Content written by
780
+ `createfile` is scanned like any other script content, so a configuration
781
+ file that only lists tool names (a Sysmon config, say) can still score.
782
+
672
783
  ### bes-siterepo-validate-layout
673
784
 
674
785
  For a BigFix [Git External Custom Site](https://help.hcl-software.com/bigfix/11.0/platform/Platform/Config/c_repository_site_git.html)
@@ -1,3 +1,3 @@
1
1
  """To support running this directly as a python module."""
2
2
 
3
- __version__ = "2.1.1"
3
+ __version__ = "2.3.0"
@@ -28,6 +28,16 @@ MUSTACHE_RE = re.compile(
28
28
  r"\s*[#/^!&>]?\s*[\w.-]+\s*\}\}"
29
29
  )
30
30
 
31
+ # a DTD, which can only come in the prolog: before it there may be only a BOM,
32
+ # whitespace, the XML declaration, comments and processing instructions. Each
33
+ # comment or PI stops at its own first `-->` / `?>` and whitespace is one
34
+ # character at a time, so the pattern cannot stretch past the prolog (to a
35
+ # plist's `<?xml ...?><!DOCTYPE plist>` inside an action) or backtrack across
36
+ # a file full of comments.
37
+ PROLOG_DOCTYPE_RE = re.compile(
38
+ "^\ufeff?(?:\\s|<\\?(?:[^?]|\\?(?!>))*\\?>|<!--(?:[^-]|-(?!->))*-->)*(<!DOCTYPE)\\b"
39
+ )
40
+
31
41
  # directories never searched by discover_bes_files (hidden ones are skipped too)
32
42
  DISCOVERY_SKIP_DIRS = frozenset({"__pycache__", "node_modules"})
33
43