kashif 1.1.0__py3-none-any.whl

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 (162) hide show
  1. kashif-1.1.0.dist-info/METADATA +1277 -0
  2. kashif-1.1.0.dist-info/RECORD +162 -0
  3. kashif-1.1.0.dist-info/WHEEL +5 -0
  4. kashif-1.1.0.dist-info/entry_points.txt +3 -0
  5. kashif-1.1.0.dist-info/licenses/LICENSE +21 -0
  6. kashif-1.1.0.dist-info/top_level.txt +1 -0
  7. vulnscan/__init__.py +3 -0
  8. vulnscan/__main__.py +3 -0
  9. vulnscan/apex_export.py +1131 -0
  10. vulnscan/autofix.py +1775 -0
  11. vulnscan/baseline.py +109 -0
  12. vulnscan/cfamily_frontend.py +3772 -0
  13. vulnscan/cli.py +1660 -0
  14. vulnscan/compliance.py +1906 -0
  15. vulnscan/data/compliance.json +7206 -0
  16. vulnscan/data/web/MANIFEST.json +166 -0
  17. vulnscan/data/web/cookies.json +1309 -0
  18. vulnscan/data/web/csp-bypass.json +182 -0
  19. vulnscan/data/web/ct-logs.json +546 -0
  20. vulnscan/data/web/eol.json +1 -0
  21. vulnscan/data/web/error-signatures.json +1291 -0
  22. vulnscan/data/web/exposed-paths.json +1172 -0
  23. vulnscan/data/web/favicons.json +717 -0
  24. vulnscan/data/web/hsts-preload.json.gz +0 -0
  25. vulnscan/data/web/leak-headers.json +310 -0
  26. vulnscan/data/web/malicious-hosts.json +145 -0
  27. vulnscan/data/web/observatory-v6.json +141 -0
  28. vulnscan/data/web/psl.dat.gz +0 -0
  29. vulnscan/data/web/psl.dat.meta.json +13 -0
  30. vulnscan/data/web/retire-jsrepository.json.gz +0 -0
  31. vulnscan/data/web/secret-rules.json +91 -0
  32. vulnscan/data/web/server-cve.json +1 -0
  33. vulnscan/data/web/takeover.json +897 -0
  34. vulnscan/data/web/tech.json +394 -0
  35. vulnscan/data/web/tls-profiles.json +110 -0
  36. vulnscan/deps.py +584 -0
  37. vulnscan/diffscope.py +256 -0
  38. vulnscan/erb_frontend.py +89 -0
  39. vulnscan/exporters.py +1518 -0
  40. vulnscan/external.py +98 -0
  41. vulnscan/flow.py +1108 -0
  42. vulnscan/history.py +1251 -0
  43. vulnscan/i18n/__init__.py +77 -0
  44. vulnscan/i18n/bidi.py +179 -0
  45. vulnscan/i18n/cat_apex.py +151 -0
  46. vulnscan/i18n/cat_autofix.py +98 -0
  47. vulnscan/i18n/cat_cli.py +235 -0
  48. vulnscan/i18n/cat_core2.py +46 -0
  49. vulnscan/i18n/cat_dynamic.py +234 -0
  50. vulnscan/i18n/cat_integrations.py +44 -0
  51. vulnscan/i18n/cat_misc.py +130 -0
  52. vulnscan/i18n/cat_models.py +241 -0
  53. vulnscan/i18n/cat_models_js.py +17 -0
  54. vulnscan/i18n/cat_models_jvm.py +38 -0
  55. vulnscan/i18n/cat_models_native.py +48 -0
  56. vulnscan/i18n/cat_models_other.py +80 -0
  57. vulnscan/i18n/cat_models_python.py +33 -0
  58. vulnscan/i18n/cat_projects.py +5 -0
  59. vulnscan/i18n/cat_rules.py +197 -0
  60. vulnscan/i18n/cat_rules_extra.py +152 -0
  61. vulnscan/i18n/cat_sca.py +65 -0
  62. vulnscan/i18n/cat_updater.py +59 -0
  63. vulnscan/i18n/cat_web.py +321 -0
  64. vulnscan/i18n/cat_web2.py +352 -0
  65. vulnscan/i18n/cliargs.py +311 -0
  66. vulnscan/i18n/plural.py +62 -0
  67. vulnscan/integrations/__init__.py +6 -0
  68. vulnscan/integrations/github_pr.py +524 -0
  69. vulnscan/js_frontend.py +1626 -0
  70. vulnscan/lsp.py +1382 -0
  71. vulnscan/mcp.py +2294 -0
  72. vulnscan/model.py +231 -0
  73. vulnscan/models/cpp.json +1643 -0
  74. vulnscan/models/csharp.json +1146 -0
  75. vulnscan/models/go.json +1160 -0
  76. vulnscan/models/java.json +1529 -0
  77. vulnscan/models/javascript.json +119 -0
  78. vulnscan/models/kotlin.json +556 -0
  79. vulnscan/models/php.json +1329 -0
  80. vulnscan/models/plsql.json +523 -0
  81. vulnscan/models/python.json +1372 -0
  82. vulnscan/models/ruby.json +1463 -0
  83. vulnscan/models/rust.json +1423 -0
  84. vulnscan/models/swift.json +1202 -0
  85. vulnscan/php_include.py +273 -0
  86. vulnscan/plsql_frontend.py +1466 -0
  87. vulnscan/pointsto.py +800 -0
  88. vulnscan/policy.py +2922 -0
  89. vulnscan/queries/cipher-static-iv.vql +11 -0
  90. vulnscan/queries/cors-credentials-any-origin.vql +11 -0
  91. vulnscan/queries/cors-wildcard.vql +9 -0
  92. vulnscan/queries/entry-point-without-auth.vql +9 -0
  93. vulnscan/queries/entry-reaches-shell.vql +11 -0
  94. vulnscan/queries/hardcoded-password-kwarg.vql +9 -0
  95. vulnscan/queries/js-cookie-insecure.vql +10 -0
  96. vulnscan/queries/js-settimeout-string.vql +9 -0
  97. vulnscan/queries/jwt-hardcoded-secret.vql +11 -0
  98. vulnscan/queries/jwt-weak-verification.vql +9 -0
  99. vulnscan/queries/kdf-hardcoded-salt.vql +11 -0
  100. vulnscan/queries/random-for-secret.vql +9 -0
  101. vulnscan/queries/sql-built-with-format.vql +9 -0
  102. vulnscan/queries/ssh-auto-add-host-key.vql +9 -0
  103. vulnscan/queries/ssl-wrap-socket-unverified.vql +9 -0
  104. vulnscan/queries/subprocess-shell-true-dynamic.vql +9 -0
  105. vulnscan/queries/tarfile-extractall-no-filter.vql +9 -0
  106. vulnscan/queries/tls-verify-disabled.vql +9 -0
  107. vulnscan/queries/yaml-load-without-loader.vql +9 -0
  108. vulnscan/report.py +2432 -0
  109. vulnscan/rules.py +1095 -0
  110. vulnscan/ruletest.py +2350 -0
  111. vulnscan/sca.py +1287 -0
  112. vulnscan/scanner.py +1578 -0
  113. vulnscan/semantic.py +328 -0
  114. vulnscan/server.py +1340 -0
  115. vulnscan/store.py +397 -0
  116. vulnscan/stored.py +1311 -0
  117. vulnscan/surface.py +4703 -0
  118. vulnscan/taint.py +4887 -0
  119. vulnscan/triage.py +1945 -0
  120. vulnscan/ui/app.js +2054 -0
  121. vulnscan/ui/index.html +510 -0
  122. vulnscan/ui/logo.svg +36 -0
  123. vulnscan/ui/styles.css +880 -0
  124. vulnscan/updater.py +1237 -0
  125. vulnscan/vql.py +1016 -0
  126. vulnscan/web.py +368 -0
  127. vulnscan/webscan/__init__.py +22 -0
  128. vulnscan/webscan/_htmlparser.py +594 -0
  129. vulnscan/webscan/classify.py +1110 -0
  130. vulnscan/webscan/content.py +2181 -0
  131. vulnscan/webscan/cookies.py +1327 -0
  132. vulnscan/webscan/cors.py +390 -0
  133. vulnscan/webscan/coverage.py +213 -0
  134. vulnscan/webscan/csp.py +2019 -0
  135. vulnscan/webscan/data.py +551 -0
  136. vulnscan/webscan/diff.py +1005 -0
  137. vulnscan/webscan/disclosure.py +2226 -0
  138. vulnscan/webscan/domxss.py +1674 -0
  139. vulnscan/webscan/engine.py +1355 -0
  140. vulnscan/webscan/exposure.py +1124 -0
  141. vulnscan/webscan/grade.py +921 -0
  142. vulnscan/webscan/group.py +581 -0
  143. vulnscan/webscan/headers.py +1710 -0
  144. vulnscan/webscan/htmlparse.py +320 -0
  145. vulnscan/webscan/http.py +2160 -0
  146. vulnscan/webscan/libs.py +1088 -0
  147. vulnscan/webscan/mmh3.py +58 -0
  148. vulnscan/webscan/psl.py +168 -0
  149. vulnscan/webscan/remediation.py +1246 -0
  150. vulnscan/webscan/robots.py +307 -0
  151. vulnscan/webscan/rules.py +1267 -0
  152. vulnscan/webscan/sectxt.py +477 -0
  153. vulnscan/webscan/sfv.py +359 -0
  154. vulnscan/webscan/simhash.py +300 -0
  155. vulnscan/webscan/tech.py +1234 -0
  156. vulnscan/webscan/tls/__init__.py +19 -0
  157. vulnscan/webscan/tls/assess.py +1557 -0
  158. vulnscan/webscan/tls/probe.py +678 -0
  159. vulnscan/webscan/tls/raw.py +621 -0
  160. vulnscan/webscan/tls/x509.py +689 -0
  161. vulnscan/webscan/transport.py +1491 -0
  162. vulnscan/webscan/types.py +954 -0
@@ -0,0 +1,1277 @@
1
+ Metadata-Version: 2.4
2
+ Name: kashif
3
+ Version: 1.1.0
4
+ Summary: Standalone source-code vulnerability scanner that reports findings from highest to lowest severity.
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://abdulrahmanahmedelabed-prog.github.io/vulnscan/
7
+ Project-URL: Documentation, https://abdulrahmanahmedelabed-prog.github.io/vulnscan/docs.html
8
+ Project-URL: Changelog, https://abdulrahmanahmedelabed-prog.github.io/vulnscan/changelog.html
9
+ Project-URL: Security, https://abdulrahmanahmedelabed-prog.github.io/vulnscan/security.html
10
+ Project-URL: Repository, https://github.com/abdulrahmanahmedelabed-prog/vulnscan
11
+ Project-URL: Issues, https://github.com/abdulrahmanahmedelabed-prog/vulnscan/issues
12
+ Keywords: security,sast,static-analysis,vulnerability-scanner,sarif,taint-analysis,data-flow-analysis,code-scanning,secure-code-review,devsecops,appsec,owasp,cwe,secrets-detection,lsp,oracle-apex
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Environment :: Console
15
+ Classifier: Environment :: Web Environment
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Information Technology
18
+ Classifier: Intended Audience :: System Administrators
19
+ Classifier: Natural Language :: Arabic
20
+ Classifier: Natural Language :: English
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Programming Language :: Python :: 3
23
+ Classifier: Programming Language :: Python :: 3 :: Only
24
+ Classifier: Programming Language :: Python :: 3.10
25
+ Classifier: Programming Language :: Python :: 3.11
26
+ Classifier: Programming Language :: Python :: 3.12
27
+ Classifier: Programming Language :: Python :: 3.13
28
+ Classifier: Topic :: Security
29
+ Classifier: Topic :: Software Development :: Quality Assurance
30
+ Classifier: Topic :: Software Development :: Testing
31
+ Requires-Python: >=3.10
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=8; extra == "dev"
36
+ Requires-Dist: pytest-cov>=5; extra == "dev"
37
+ Requires-Dist: ruff>=0.6; extra == "dev"
38
+ Dynamic: license-file
39
+
40
+ <p align="center">
41
+ <img src="docs/logo.svg" alt="Kashif · كاشِف — vulnscan" width="520">
42
+ </p>
43
+
44
+ <p align="center">
45
+ <b>English</b> | <a href="#arabic">العربية</a>
46
+ &nbsp;·&nbsp; <a href="https://abdulrahmanahmedelabed-prog.github.io/vulnscan/">Website</a>
47
+ &nbsp;·&nbsp; <a href="https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest">Download</a>
48
+ </p>
49
+
50
+ <a id="english"></a>
51
+
52
+ # Kashif (vulnscan) — open-source SAST with real dataflow analysis
53
+
54
+ **Kashif** (كاشِف, "the revealer") is a dependency-free static application security testing tool written in
55
+ Python. `kashif` is the name of the command (`vulnscan`, its earlier name and the Python package's, still works as
56
+ an alias). It scans source code, archives, Android apps
57
+ and (passively) websites, and produces a report ordered from **critical to info**, from the command line or
58
+ from a **local web UI** in English and Arabic.
59
+
60
+ | Dashboard | Finding with its data-flow trace |
61
+ |---|---|
62
+ | ![Kashif dashboard](docs/screenshots/dashboard-en-light.png) | ![A SQL injection finding with its source-to-sink trace](docs/screenshots/trace-en-light.png) |
63
+
64
+ > **Authorization first:** scan only what you own or are authorized in writing to test. Scanning other
65
+ > people's systems without permission may be illegal. Web targets require the `--authorized` flag.
66
+
67
+ ## What it does
68
+
69
+ - **Dataflow (taint) analysis in 12 languages** — Python, JavaScript/TypeScript, Java, Kotlin, C#, Go, PHP,
70
+ C/C++, Rust, Swift, Ruby and PL/SQL. Untrusted input is tracked across functions, classes and files, and
71
+ every finding carries the full source → sink path.
72
+ - **Precision features** — flow-sensitive analysis with constant folding and dead-branch pruning;
73
+ context-sensitive (k=2) points-to analysis; context-specific sanitizers (`html.escape` protects HTML only,
74
+ not SQL or a shell); second-order (stored) injection through database tables.
75
+ - **Rules and models** — 153 pattern rules, 48 dataflow and APEX rules and 19 built-in VQL queries (VQL is
76
+ Kashif's declarative query language over the program database), over 6,357 modelled library APIs
77
+ (1,044 sources, 4,532 sinks, 781 sanitizers).
78
+ - **Fewer false positives on real code** — test, documentation and example code is recognised by its path: fixture
79
+ noise there is dropped and the rest is lowered to info; vendored bundles are skipped. On the 35 open-source projects
80
+ (of 38) that 0.9 could finish, findings went from 17,228 to 2,607 (critical and high: 4,345 to 783); half of 0.9's
81
+ findings were in test, docs and example code.
82
+ - **Fast on large code** — `--jobs N` spreads the per-file work over your CPUs and `--cache DIR` answers an unchanged
83
+ project from its cache with identical findings. Django (6,973 files) takes 311–411 s cold on 4 vCPUs (0.9: 594 s)
84
+ and 3.5 s warm.
85
+ - **Autofix** — `--fix` / `--fix-dry-run` apply verified, deterministic fixes for 39 rules (38 automatically), shown as
86
+ diffs in the UI, the reports, SARIF and the editor.
87
+ - **Oracle APEX & ORDS** — APEX application exports, plug-ins and PL/SQL packages.
88
+ - **Secrets** — provider-specific patterns plus entropy-based detection, and `kashif history` for every secret ever
89
+ committed to git, even if a later commit deleted it.
90
+ - **Dependencies (SCA) with reachability** — 23 manifest and lockfile types; known vulnerabilities from
91
+ [OSV.dev](https://osv.dev), each marked by whether your code imports the package and calls the vulnerable function
92
+ (the OSV lookup is optional and the only part of a code scan that uses the network).
93
+ - **Archives & Android** — zip, tar.gz, whl, APK, JAR, AAR, DEX; with [jadx](https://github.com/skylot/jadx)
94
+ installed, bytecode is decompiled and analyzed.
95
+ - **Passive web scanning** — security headers, CSP, TLS, cookies, commonly exposed paths, and a crawl with
96
+ rate limiting and an honest User-Agent. No payloads, no form submission.
97
+ - **Team workflow** — triage decisions kept in the repository (`kashif triage`), policy as code (`kashif.yml`),
98
+ compliance mapping to 10 frameworks with an auditor report (`kashif compliance`), an attack-surface map
99
+ (`kashif surface`) and a kit to write and test your own rules (`kashif rules`).
100
+ - **AI coding assistants** — `kashif mcp` is an MCP server, so Claude Code, Cursor, VS Code agents, Windsurf and Zed
101
+ can check the code they write, locally and offline.
102
+ - **Outputs** — console, Markdown, JSON, HTML and SARIF 2.1.0 (validated against the OASIS schema; works with
103
+ GitHub Code Scanning and the VS Code SARIF viewer), with stable fingerprints; plus DefectDojo, SonarQube,
104
+ GitLab SAST, Code Climate, JUnit XML, CSV, Jira, GitHub Issues, AWS Security Hub (ASFF) and OCSF.
105
+
106
+ ## Install
107
+
108
+ ### One line (verifies the SHA-256 before installing)
109
+
110
+ ```bash
111
+ # macOS and Linux: installs kashif (and a vulnscan alias) into ~/.local/bin
112
+ curl -fsSL https://abdulrahmanahmedelabed-prog.github.io/vulnscan/install.sh | sh
113
+ ```
114
+
115
+ ```powershell
116
+ # Windows: installs into %LOCALAPPDATA%\Programs\Kashif and adds it to your PATH
117
+ irm https://abdulrahmanahmedelabed-prog.github.io/vulnscan/install.ps1 | iex
118
+ ```
119
+
120
+ ```bash
121
+ # Homebrew (macOS and Linux)
122
+ brew tap kashif/vulnscan https://github.com/abdulrahmanahmedelabed-prog/vulnscan
123
+ brew install kashif
124
+ ```
125
+
126
+ All three download the release binary over HTTPS and check it against the release's `SHA256SUMS.txt`. Because
127
+ they download with curl, macOS does not quarantine the file, so Gatekeeper does not block the (not yet notarized)
128
+ binary.
129
+
130
+ ### Download a binary (nothing else needed)
131
+
132
+ Get the file for your platform from the
133
+ [latest release](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest):
134
+
135
+ | Platform | File |
136
+ |---|---|
137
+ | Windows x64 (portable) | [`kashif-windows-x86_64.exe`](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest/download/kashif-windows-x86_64.exe) — double-click to open the web UI |
138
+ | Windows x64 (setup wizard) | [`kashif-setup.exe`](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest/download/kashif-setup.exe) — installs Kashif, optionally adds it to PATH, adds Start-menu and desktop shortcuts, and uninstalls from Windows Settings |
139
+ | Linux x86-64 (Ubuntu 22.04+, Debian 12, RHEL 9+) | [`kashif-linux-x86_64`](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest/download/kashif-linux-x86_64) |
140
+ | macOS Apple Silicon | [`kashif-macos-arm64`](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest/download/kashif-macos-arm64) |
141
+ | macOS Intel | [`kashif-macos-x86_64`](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest/download/kashif-macos-x86_64) |
142
+
143
+ ```bash
144
+ # Linux
145
+ chmod +x kashif-linux-x86_64
146
+ ./kashif-linux-x86_64 # opens the web UI
147
+ ./kashif-linux-x86_64 ./project --fail-on high
148
+
149
+ # macOS: the binary is not notarized by Apple. Remove the quarantine flag once
150
+ # (or right-click the file > Open on first launch):
151
+ chmod +x kashif-macos-arm64
152
+ xattr -d com.apple.quarantine kashif-macos-arm64
153
+ ./kashif-macos-arm64
154
+ ```
155
+
156
+ **Verify the download.** Every release ships `SHA256SUMS.txt`, a CycloneDX SBOM (`kashif-sbom.cdx.json`)
157
+ and signed SLSA build provenance:
158
+
159
+ ```bash
160
+ sha256sum -c SHA256SUMS.txt --ignore-missing
161
+ gh attestation verify kashif-linux-x86_64 --repo abdulrahmanahmedelabed-prog/vulnscan
162
+ ```
163
+
164
+ ### Install with pip (Python 3.10+)
165
+
166
+ ```bash
167
+ pip install git+https://github.com/abdulrahmanahmedelabed-prog/vulnscan
168
+ ```
169
+
170
+ Kashif has **zero runtime dependencies**. You can also run it from a clone with `python -m vulnscan`.
171
+
172
+ ### Updating
173
+
174
+ The binaries update themselves. In the web UI open **Settings > Updates** and select **Update now**, then
175
+ **Restart now**; a small "Update available" badge appears in the sidebar when a newer release is out. From a
176
+ terminal:
177
+
178
+ ```bash
179
+ kashif update # check, confirm, download, verify, install
180
+ kashif update --check # only check: exit code 10 when an update is available, 0 when up to date
181
+ kashif update --yes # no confirmation prompt (scripts)
182
+ ```
183
+
184
+ The update is downloaded only from GitHub over HTTPS, checked against the release's `SHA256SUMS.txt`, refused if
185
+ it is not newer, and tested (`--version`) before it atomically replaces the running binary; the previous binary is
186
+ kept as `<name>.old` until the next start, and any failure rolls back. On macOS, an Intel binary running under
187
+ Rosetta is offered the native Apple Silicon build. If the binary's folder is not writable (for example
188
+ `/usr/local/bin`), run `sudo kashif update`. pip and source installs are never modified: the UI and
189
+ `kashif update` show the exact command instead (`python -m pip install --upgrade ...` or `git pull`).
190
+ A pip install made before 1.0.2 is the distribution `vulnscan` (from 1.0.2 on it is `kashif`): remove it before
191
+ installing the new version, or the two would own the same files (`vulnscan` on PyPI is an unrelated project):
192
+
193
+ ```bash
194
+ python -m pip uninstall -y vulnscan kashif
195
+ pip install git+https://github.com/abdulrahmanahmedelabed-prog/vulnscan
196
+ ```
197
+ The check asks `api.github.com` for the latest release at most every 6 hours and sends nothing about your code;
198
+ turn off **Check for updates automatically** in Settings to disable it.
199
+
200
+ ## Quick start
201
+
202
+ ```bash
203
+ kashif ./my-project # colored console report
204
+ kashif ./my-project --all-formats report # report.md / .json / .html / .sarif
205
+ kashif app.apk -f html -o report.html # archives and APKs
206
+ kashif . --fail-on high --exclude "tests/*" # CI gate
207
+ kashif . --no-deps --no-external # fully offline
208
+ kashif https://my-site.example --authorized # passive web scan of a site you own
209
+ kashif ui # web UI on http://127.0.0.1:8765
210
+ kashif . --lang en # English-only output (ar, en, both; or set VULNSCAN_LANG)
211
+ ```
212
+
213
+ Every finding, remediation, data-flow step and scan note is available in English and Arabic: the web UI switches
214
+ language in one click, `--lang` controls the console and the Markdown/HTML reports, and SARIF is English-first
215
+ for GitHub Code Scanning (Arabic kept in the result properties).
216
+
217
+ The web UI (dashboard, scan, findings, reports, rules, settings) listens on 127.0.0.1 only; data is stored in
218
+ `~/.vulnscan` (or `VULNSCAN_HOME`).
219
+
220
+ ## Command reference
221
+
222
+ `kashif --help` lists every option and sub-command; `kashif <sub-command> --help` shows the options of one.
223
+ `python3 -m vulnscan ...` works the same way, and `vulnscan` is kept as an alias of `kashif`.
224
+
225
+ ```bash
226
+ kashif . -f gitlab-sast -o gl-sast-report.json # GitLab Security tab and merge-request widget
227
+ kashif . -f codeclimate -o gl-code-quality.json # GitLab Code Quality
228
+ kashif . --export defectdojo=dd.json --export junit=kashif.xml # extra formats from the same scan
229
+ kashif . --triage --fail-on high # honour the decisions in .kashif/triage.json
230
+ kashif . --policy strict # a builtin gate; a kashif.yml in the project applies by itself
231
+ kashif . --compliance owasp,pci --audit-report audit.html
232
+ kashif ui # local web UI
233
+ kashif lsp # language server for editors
234
+ kashif mcp # MCP server for AI coding assistants
235
+ kashif export report.json -f sonarqube -o sonar.json
236
+ kashif compliance report.json -f html -o audit.html
237
+ kashif history . --max-commits 500 # secrets in git history (alias: secrets-history)
238
+ kashif triage set <fingerprint> false_positive -j "the value is a constant"
239
+ kashif triage list
240
+ kashif policy init --preset startup # writes kashif.yml
241
+ kashif policy check report.json
242
+ kashif surface . -f openapi -o surface.json # attack-surface map
243
+ kashif rules new my-pack && kashif rules test my-pack
244
+ kashif update --check
245
+ ```
246
+
247
+ | Sub-command | What it does |
248
+ |---|---|
249
+ | `ui` | Local web UI on 127.0.0.1 (dashboard, scans, findings, reports, settings). |
250
+ | `lsp` | Language server: findings underlined as you type, quick fixes (setup: `editors/README.md`). |
251
+ | `mcp` | Model Context Protocol server, so Claude Code, Cursor, VS Code agents, Windsurf and Zed can check the code they write, locally and offline: `claude mcp add kashif -- kashif mcp`. `kashif mcp --print-config all` prints the configuration of each client. Tools: scan_path, scan_snippet, get_finding, explain_rule, list_rules, suggest_fix. It reads only inside the project roots and never runs your code. |
252
+ | `export` | Converts a JSON report (`-f json`) to DefectDojo, SonarQube, JUnit XML, CSV, Jira CSV, GitHub Issues, AWS Security Hub (ASFF), OCSF, GitLab SAST, Code Climate or the Kashif risk score (`kashif export --list-formats`). The scan's own `-f` accepts the same formats. The risk score (0-10) is a triage aid, not a CVSS score. |
253
+ | `compliance` | Maps findings (a JSON report, a SARIF file of any tool, or a path to scan) to OWASP Top 10, OWASP API Top 10, ASVS, CWE Top 25, PCI DSS, NIST SSDF, NIST SP 800-53, ISO/IEC 27001, HIPAA and GDPR, and writes a printable auditor report. Evidence for an assessment, not a certification. |
254
+ | `history` | Every secret ever committed, even if a later commit deleted it, with the commit that introduced it and whether it is still at HEAD. Secrets are always redacted. Needs only the `git` executable. |
255
+ | `triage` | Decisions about findings (false positive, accepted risk with an expiry date, won't fix, fixed) in `.kashif/triage.json`, with author, justification and an audit log, reviewed in pull requests like code. `kashif triage stats` reports MTTR, ages and SLA breaches. |
256
+ | `policy` | Policy as code: a `kashif.yml` gate (severity thresholds, counts, new findings only, forbidden CWEs/rules/OWASP categories, per-path scopes, exceptions with an approver and an expiry). `kashif policy check report.json` explains each decision. |
257
+ | `surface` | Attack-surface map: HTTP routes, CLI commands, queue consumers and jobs with their untrusted inputs, the visible authentication and the sinks they reach; Markdown, CSV, JSON, Mermaid, Graphviz or an OpenAPI 3.1 skeleton. Static analysis only. |
258
+ | `rules` | Write and test your own rules: `new` scaffolds a rule pack, `test` checks fixtures annotated with `# kashif: expect RULE`, `lint`, `pack` (one `.kashifpack` file with a SHA-256), `verify`, `install`, `list`, `docs`. Scan with installed packs: `--pack NAME` or `--packs`. |
259
+ | `update` | Installs the latest official release after verifying it (`--check` only checks). |
260
+ | `update-data` | `kashif update-data --web` installs the web scanner's data snapshot of the latest release after verifying its SHA-256 (`--check` only checks). Nothing about the sites you scan is sent; without it the bundled snapshot is used. |
261
+
262
+ Scan options added in 1.0: `--export FORMAT=FILE` (repeatable), `--risk-score`, `--compliance FRAMEWORKS`,
263
+ `--audit-report FILE`, `--triage[=FILE]`, `--triage-update` (CI on the main branch only), `--triage-show STATUSES`,
264
+ `--sla critical=7,high=30`, `--fail-on-sla`, `--policy[=FILE|PRESET]`, `--no-policy`, `--policy-reports-dir DIR`,
265
+ `--pack NAME`, `--packs`. A `kashif.yml` found in the scanned folder is applied automatically and decides the exit
266
+ code together with `--fail-on`; a policy or triage file in a pull request can relax the gate for that pull request,
267
+ so review changes to them like code (`kashif triage diff`).
268
+
269
+ ## CI and GitHub Code Scanning (SARIF)
270
+
271
+ ```yaml
272
+ permissions:
273
+ contents: read
274
+ security-events: write # required to upload SARIF
275
+ steps:
276
+ - uses: actions/checkout@v4
277
+ - uses: actions/setup-python@v5
278
+ with: { python-version: "3.12" }
279
+ - run: pip install git+https://github.com/abdulrahmanahmedelabed-prog/vulnscan
280
+ - run: kashif . --no-deps -f sarif -o vulnscan.sarif
281
+ - uses: github/codeql-action/upload-sarif@v3
282
+ if: always()
283
+ with:
284
+ sarif_file: vulnscan.sarif
285
+ ```
286
+
287
+ Findings appear in the Security tab and inline on pull requests, with a numeric severity, CWE and the dataflow
288
+ path. Fingerprints are stable across line shifts and reformatting, so alerts are not duplicated.
289
+
290
+ ### Pull-request review comments, GitLab, pre-commit
291
+
292
+ - **GitHub Action** (`uses: abdulrahmanahmedelabed-prog/vulnscan@v1.1.0`): scans the pull request, uploads SARIF and
293
+ posts one review with inline comments on the changed lines only (rule, severity, remediation, data-flow path),
294
+ plus a summary comment that is updated, not duplicated, on every push.
295
+ - **Diff-aware scanning** anywhere: `kashif . --diff-base origin/main` reports only what the branch introduces
296
+ (the whole project is still analysed, so cross-file flows stay correct); `--fail-on` then gates on new findings only.
297
+ - **GitLab**: `-f gitlab-sast` (Security tab and merge-request widget; GitLab SAST report schema 15.0) and
298
+ `-f codeclimate` (Code Quality); a ready GitLab CI job is in `docs/production.md`. Scan the repository root so
299
+ that paths are relative to it.
300
+ - **pre-commit**: a `kashif` hook that checks only staged changes.
301
+
302
+ Full guide: `docs/integrations.md`.
303
+
304
+ ## IDE integration (VS Code, JetBrains, Neovim, Helix, Zed, Sublime, Emacs)
305
+
306
+ `kashif lsp` is a Language Server: vulnerabilities are underlined while you work, with the data-flow path as
307
+ related locations, remediation on hover, and quick fixes to suppress a reviewed finding or add it to the baseline.
308
+ The VS Code extension (`kashif-vscode.vsix`, attached to every release) runs it for you; other editors connect to
309
+ the same server. Setup for each editor: `editors/README.md`.
310
+
311
+ ### Baseline: report only what's new
312
+
313
+ ```bash
314
+ kashif . --write-baseline .vulnscan-baseline.json # once; commit the file (fingerprints only)
315
+ kashif . --baseline .vulnscan-baseline.json --fail-on high # later: new findings only
316
+ ```
317
+
318
+ ### Audit profile
319
+
320
+ `--audit` additionally lists every dangerous call (eval, shell, SQL, pickle, …) that dataflow analysis could
321
+ not prove is reached by untrusted input — useful for manual security reviews where you want the whole attack
322
+ surface, not just proven flows.
323
+
324
+ ## Accuracy: OWASP Benchmark
325
+
326
+ Measured on the [OWASP Benchmark for Python](https://github.com/OWASP-Benchmark/BenchmarkPython) v0.1
327
+ (1,230 test cases) and the [OWASP Benchmark for Java](https://github.com/OWASP-Benchmark/BenchmarkJava) v1.2
328
+ (2,740 test cases). Score = mean over categories of TPR − FPR (Youden's J), the scoring method OWASP uses,
329
+ computed by this project's own scorer (`bench/score_owasp.py`), not by OWASP's scorecard tool.
330
+ **Python: 74.0% · Java: 98.3%.**
331
+
332
+ | Category | Py TPR % | Py FPR % | Py score | Java TPR % | Java FPR % | Java score |
333
+ |---|---:|---:|---:|---:|---:|---:|
334
+ | cmdi (command injection) | 100.0 | 42.9 | 57.1 | 100.0 | 0.0 | 100.0 |
335
+ | codeinj (code injection) | 100.0 | 45.5 | 54.5 | — | — | — |
336
+ | crypto (weak cipher) | — | — | — | 100.0 | 0.0 | 100.0 |
337
+ | deserialization (deserialization) | 100.0 | 8.3 | 91.7 | — | — | — |
338
+ | hash (weak hashing) | 100.0 | 0.0 | 100.0 | 100.0 | 0.0 | 100.0 |
339
+ | ldapi (LDAP injection) | 100.0 | 7.7 | 92.3 | 100.0 | 0.0 | 100.0 |
340
+ | pathtraver (path traversal) | 92.3 | 46.6 | 45.7 | 100.0 | 0.0 | 100.0 |
341
+ | redirect (open redirect) | 100.0 | 47.6 | 52.4 | — | — | — |
342
+ | securecookie (insecure cookie) | 100.0 | 0.0 | 100.0 | 100.0 | 0.0 | 100.0 |
343
+ | sqli (SQL injection) | 100.0 | 0.0 | 100.0 | 100.0 | 0.0 | 100.0 |
344
+ | trustbound (trust boundary) | 100.0 | 36.8 | 63.2 | 100.0 | 0.0 | 100.0 |
345
+ | weakrand (weak randomness) | 100.0 | 0.0 | 100.0 | 100.0 | 0.0 | 100.0 |
346
+ | xpathi (XPath injection) | 76.5 | 20.0 | 56.5 | 100.0 | 0.0 | 100.0 |
347
+ | xss (cross-site scripting) | 100.0 | 43.1 | 56.9 | 100.0 | 18.2 | 81.8 |
348
+ | xxe (XML external entities) | 100.0 | 35.0 | 65.0 | — | — | — |
349
+ | **Overall** | | | **74.0** | | | **98.3** |
350
+
351
+ Each suite is scanned whole, as one application (the Python repository, the Java `src/main` tree), with the
352
+ default profile. Reproduce either with one command:
353
+
354
+ ```bash
355
+ git clone --depth 1 https://github.com/OWASP-Benchmark/BenchmarkPython && python bench/score_owasp.py BenchmarkPython
356
+ git clone --depth 1 https://github.com/OWASP-Benchmark/BenchmarkJava && python bench/score_owasp.py BenchmarkJava
357
+ ```
358
+
359
+ The engine is never tuned to benchmark files: no test-case names, paths or expected results are encoded in
360
+ it. The weakest categories (Python path traversal, XSS and redirects) are where values need deeper tracking; that
361
+ gap is reported as measured.
362
+
363
+ **About the Java score (76.3% in 0.9 → 98.3% in 1.0).** Two general Java call-resolution fixes explain the whole
364
+ change. A bare call such as `helper(x)` now resolves to the enclosing class's own method, so the helper's body is
365
+ analysed instead of passing taint straight through (258 false positives became true negatives); and a common
366
+ library method such as `toString` or `getValue` is no longer bound to an unrelated project method of the same name
367
+ (41 missed vulnerabilities are now found). No test case moved in the wrong direction. An independent audit found no
368
+ Benchmark-specific names, paths or patterns in the engine; a fully renamed copy of the suite scores the same 98.3%,
369
+ and 516 of 516 mutation tests behaved correctly (renamed safe cases stay quiet; each one made really vulnerable is
370
+ reported). Caveats: the Benchmark is a synthetic suite, so the score is not a measure of accuracy on real code (the
371
+ same audit found engine limitations that show on real code and do not affect this score), and 38 Java XSS false
372
+ positives remain (FPR 18.2%) because HTML escaping is not credited when the escaped value is the format string of
373
+ `format`/`printf`.
374
+
375
+ ## Languages and targets
376
+
377
+ | Target | Coverage |
378
+ |---|---|
379
+ | Dataflow (taint) | Python, JavaScript/TypeScript, Java, Kotlin, C#, Go, PHP, C/C++, Rust, Swift, Ruby, PL/SQL |
380
+ | Oracle | APEX application exports, plug-ins, PL/SQL packages, ORDS |
381
+ | Android / JVM | APK, JAR, AAR, DEX (decompiled with jadx when installed) |
382
+ | Config & CI | Dockerfile, docker-compose, GitHub Actions, AndroidManifest, iOS plist, config files |
383
+ | Web (passive) | headers, CSP, TLS, cookies, exposed paths, rate-limited crawl (`--authorized` required) |
384
+
385
+ ## Passive web scanning
386
+
387
+ `kashif https://my-site.example --authorized` reads what a site already serves, the way a browser would, and judges
388
+ it against 184 rules (34 kept from 1.0 with the same ids, 150 new): transport and HSTS, Content-Security-Policy,
389
+ framing and the other response headers, CORS, cookies, page content and the page's own JavaScript, information
390
+ disclosure, TLS and certificates, components (retire.js data), exposed files and `security.txt`. It never sends a
391
+ payload, never submits a form, never fuzzes or guesses, never spoofs headers, sends an honest User-Agent
392
+ (`Kashif/<version>`) and keeps at least `--delay` seconds (floor 0.2) between two requests to one host.
393
+
394
+ ```bash
395
+ kashif https://my-site.example --authorized # standard profile (at most 45 requests)
396
+ kashif https://my-site.example --authorized --web-profile minimal # the page and its redirects only (at most 10)
397
+ kashif https://my-site.example --authorized --deep # + commonly exposed files (at most 150)
398
+ kashif https://my-site.example --authorized --crawl --max-pages 50 # + same-origin pages (same scheme, host and port)
399
+ kashif https://my-site.example --authorized --web-sensitivity strict -f sarif -o web.sarif
400
+ kashif https://my-site.example --authorized --compare-previous # diff against the last saved scan of the site
401
+ kashif https://my-site.example --authorized --compare old-report.json # or a scan id from the local history
402
+ kashif update-data --web # newer web data from the latest release
403
+ ```
404
+
405
+ | Option | Meaning |
406
+ |---|---|
407
+ | `--web-profile minimal\|standard\|deep` | `minimal` is the 1.0 single fetch (the entry chain, at most 10 requests); `standard` (default) adds the http/https counterpart, one cookieless CORS GET with `Origin: https://kashif-cors-check.invalid`, `robots.txt`, `security.txt`, the favicon, `/sitemap.xml` (with `--crawl`) and up to 15 of the page's own scripts and styles (at most 45); `deep` (`--deep`) adds a fixed list of commonly exposed files, the login and administration pages of a detected platform (fetched once, nothing submitted), soft-404 baselines, third-party scripts, source maps and images (at most 150). Crawled pages come on top. |
408
+ | `--web-sensitivity strict\|default\|paranoid` | `strict` reports certain findings only, `default` certain and firm, `paranoid` everything, including the paranoid-only checks. Every finding carries its confidence (`certain`, `firm` or `tentative`). |
409
+ | `--crawl`, `--max-pages N`, `--max-depth N`, `--ignore-robots` | Breadth-first crawl of same-origin links (same scheme, host and port), at most 500 pages (default 20, depth 2); `robots.txt` is honoured unless you own the site and pass `--ignore-robots`. Needs `standard` or `deep`: `minimal` cannot crawl. A scan stops sending after 600 s or 50 MB received. |
410
+ | `--compare-previous`, `--compare ID\|FILE` | New, resolved and unchanged findings, grade changes and posture changes ("CSP changed", "new third-party script host", "certificate renewed"). `--compare-previous` keeps the scan in the local history (`~/.vulnscan`, or `$VULNSCAN_HOME`) and prints its id on stderr; `--compare` takes such an id (also on the UI's Reports page and in `$VULNSCAN_HOME/index.json`) or a JSON report (`-f json`). In CI, use `--compare previous.json`. `kashif history` is unrelated (it searches git history for secrets). |
411
+ | `--fail-on-inconclusive` | Exit code 1 when a WAF, challenge or rate limit answered instead of the site (Kashif grade `?` or WEB990), which `--fail-on` alone lets pass. |
412
+ | `--ignore-rule ID` | Leave a web rule out of the report and of `--fail-on` (the grades still count it). |
413
+ | `--web-cookie-ignore NAME` | Leave a cookie out of the cookie checks (repeatable). |
414
+ | `--third-party-lookups` | Allow lookups that reveal the site's name to a third party. Off by default; in 1.1 no check makes such a lookup (the HSTS preload list and certificate transparency come from bundled data and the certificate itself). |
415
+ | `--no-proxy` | Do not use `HTTP(S)_PROXY`. Only `http://` proxies are supported; any other proxy setting stops the scan with a proxy error (exit code 2; in the JSON report `web.error.code` starts with `proxy`), never a silent direct connection. Through a proxy, DNS-based checks are not tested and TLS findings are tentative, so they appear only with `--web-sensitivity paranoid`; use `--no-proxy` or `NO_PROXY` to assess TLS directly. |
416
+
417
+ Every report shows three grades (the Kashif Web Grade A+ to F, an MDN HTTP Observatory-compatible score, and an
418
+ SSL Labs-compatible TLS grade that excludes the attack-only tests Kashif does not perform), an honest coverage table
419
+ (passed, failed, not applicable, not tested, inconclusive: a check that did not run is never shown as passed), the
420
+ site inventory (security headers, CSP, cookies, TLS, technologies, third parties), copy-paste fixes for 18
421
+ platforms (nginx, Apache httpd, IIS, Caddy, Express, Node.js, Django, Flask, Spring, Tomcat, ASP.NET Core, ASP.NET,
422
+ PHP, Laravel, Symfony, Rails, Cloudflare, F5 BIG-IP; the detected platforms first) and, with a previous scan, the
423
+ diff. SARIF results carry `properties.precision` and the tags `external/cwe/cwe-N`, `wstg:…`,
424
+ `asvs4:…` and `asvs5:…`; the JSON report has the same data under the `web` key. All rules, their mappings and
425
+ default severities are listed in [docs/web-checks.md](docs/web-checks.md); [docs/web-scanning.md](docs/web-scanning.md)
426
+ describes the traffic, the profiles, the reports and the upgrade from 1.0.
427
+
428
+ **In CI** (full example in [docs/web-scanning.md](docs/web-scanning.md#using-it-in-ci)):
429
+ `kashif https://staging.example.com --authorized --fail-on high --fail-on-inconclusive -f sarif -o kashif-web.sarif`.
430
+ Exit code 0 means the gate passed, 1 that it failed (a finding at or above `--fail-on`, the policy gate, or an
431
+ inconclusive scan with `--fail-on-inconclusive`), 2 that nothing was judged (`--authorized` missing, a rejected
432
+ option combination, or a site that could not be reached; `-o` then still writes a report whose `web.status` is
433
+ `"unreachable"`). Upload the SARIF with `github/codeql-action/upload-sarif` and `category: kashif-web`, so it does not
434
+ replace the code scan's results; web alerts carry a URL, not a file location, so they never annotate pull-request
435
+ lines. Keep the JSON report of each run and pass `--compare previous.json` to the next one to see regressions.
436
+
437
+ **Policy files:** for a URL, pass the file explicitly (`--policy kashif.yml`); none is picked up automatically.
438
+ `rules.disable` and `rules.severity` change what the gate counts, not the report (use `--ignore-rule` to hide a
439
+ rule), and the default gate fails on `high`, so set `gate.fail_on`:
440
+
441
+ ```yaml
442
+ version: 1
443
+ gate:
444
+ fail_on: medium # the default gate fails on high
445
+ rules:
446
+ disable:
447
+ - id: WEB071
448
+ reason: "certificates are renewed automatically 30 days before expiry"
449
+ ```
450
+
451
+ **What a passive scan cannot find:** it reads anonymous pages only, and it does not test injection, XSS,
452
+ authentication, access control or business logic; certificate revocation (CRL/OCSP) is not checked either. A grade
453
+ measures configuration hygiene, not the absence of vulnerabilities: pair the web scan with a code scan (SAST) and an
454
+ authorised active test.
455
+
456
+ ## Limitations
457
+
458
+ - Static analysis finds common patterns and flows; it does not replace human review or penetration testing.
459
+ - False positives and misses happen. Suppress a reviewed line with `# nosec` or `// vulnscan: ignore`, or a
460
+ rule with `--ignore-rule`.
461
+ - Compared with CodeQL, Semgrep, SonarQube or Snyk Code, Kashif has fewer library models (about 6,350 modelled APIs
462
+ and 153 pattern rules) and less real-world tuning on large codebases (1.0 was tuned on 38 open-source projects).
463
+ Its strengths are running fully locally with zero dependencies, English and Arabic output, Oracle APEX,
464
+ archives/APKs and passive web checks in one tool.
465
+ - Not modelled yet: templates other than Jinja (EJS, ERB and similar), values that reach a PHP file through
466
+ `include`, and values that flow through files or databases outside the scanned code. Large projects need memory:
467
+ Django (about 7,000 files) peaks at about 3.5 GB.
468
+ - Without jadx, APK/JAR contents are scanned as text only; decompiled code may differ from the original source.
469
+ - The web scan is passive only: no active testing of any kind. It sees anonymous pages only, does not test
470
+ injection, XSS, authentication, access control or business logic, and does not check certificate revocation;
471
+ its grade measures configuration hygiene, not the absence of vulnerabilities.
472
+
473
+ ## Production use
474
+
475
+ From 1.0 Kashif follows semantic versioning with a written stability contract: command-line flags and exit codes,
476
+ the JSON/SARIF/GitLab/Code Climate report schemas, finding fingerprints and baseline files, rule IDs, suppression
477
+ comments, LSP settings and the action's inputs do not break within 1.x. A container image is published for
478
+ `linux/amd64` and `linux/arm64` (non-root, works with a read-only root filesystem):
479
+
480
+ ```bash
481
+ docker run --rm -v "$PWD:/src" ghcr.io/abdulrahmanahmedelabed-prog/kashif:1 .
482
+ ```
483
+
484
+ The contract, the support policy and the deployment recipes (CI, air-gapped networks, a team dashboard behind an
485
+ authenticating reverse proxy, scaling) are in [docs/production.md](docs/production.md).
486
+
487
+ ## Security policy
488
+
489
+ Please report vulnerabilities in Kashif privately via GitHub's
490
+ [private vulnerability reporting](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/security/advisories/new);
491
+ see [SECURITY.md](SECURITY.md). All GitHub Actions in this repository are pinned by commit SHA, an OpenSSF
492
+ Scorecard workflow runs on the repository, and every release ships checksums, an SBOM and signed SLSA
493
+ provenance.
494
+
495
+ ## About
496
+
497
+ Kashif is developed by the Programming Department at the Islamic University of Gaza. Contact: [its@iugaza.edu.ps](mailto:its@iugaza.edu.ps) and [aelabed@iugaza.edu.ps](mailto:aelabed@iugaza.edu.ps)
498
+
499
+ ## License
500
+
501
+ [MIT](LICENSE).
502
+
503
+ ---
504
+
505
+ <a id="arabic"></a>
506
+
507
+ <p dir="rtl"><a href="#english">English</a> | <b>العربية</b></p>
508
+
509
+ # كاشِف (vulnscan) — فاحص ثغرات مستقل لأي برنامج
510
+
511
+ > **كاشِف** هو الاسم العربي للأداة؛ و`kashif` هو اسم الأمر (ويبقى `vulnscan`، اسمه السابق واسم حزمة Python، اسمًا بديلًا يعمل كما هو).
512
+
513
+ أداة بلغة Python (بدون أي اعتماديات خارجية) تفحص **أي برنامج** وتُخرج تقريرًا
514
+ مرتبًا **من الأعلى خطورة إلى الأقل**: حرج ← عالٍ ← متوسط ← منخفض ← معلوماتي.
515
+ تعمل من سطر الأوامر، أو من **واجهة رسومية محلية** بلوحة تحكم وتقارير وإعدادات.
516
+
517
+ | لوحة التحكم | نتيجة مع مسار تدفق البيانات وطريقة الإصلاح |
518
+ |---|---|
519
+ | ![لوحة تحكم كاشِف](docs/screenshots/dashboard-ar-light.png) | ![نتيجة حقن SQL مع مسارها من المصدر إلى نقطة الخطر](docs/screenshots/trace-ar-light.png) |
520
+
521
+ | فحص جديد: مجلد أو ملف مضغوط أو موقع | التقارير والمقارنة (الوضع الداكن) |
522
+ |---|---|
523
+ | ![شاشة الفحص الجديد](docs/screenshots/scan-ar-light.png) | ![التقارير في الوضع الداكن](docs/screenshots/reports-ar-dark.png) |
524
+
525
+ > ⚠️ **الصلاحية أولًا:** افحص فقط ما تملكه أو ما لديك تصريح كتابي بفحصه. فحص أنظمة الآخرين دون إذن
526
+ > قد يكون مخالفًا للقانون. فحص عناوين الويب لا يعمل إلا مع العلامة `--authorized`.
527
+
528
+ ## ماذا يفحص؟
529
+
530
+ | الهدف | مثال | ما يحدث |
531
+ |---|---|---|
532
+ | مجلد مصدر بأي لغة | `kashif ./my-app` | يمر على كل الملفات النصية ويطبّق 153 قاعدة نمطية و48 قاعدة تدفق بيانات وAPEX و19 استعلام VQL |
533
+ | ملف واحد | `kashif server.py` | يفحص الملف وحده |
534
+ | أرشيف / حزمة | `kashif app.apk` أو `.jar` `.zip` `.whl` `.tar.gz` | يفكّه في مجلد مؤقت ويفحص محتواه |
535
+ | عنوان ويب (سلبي) | `kashif https://my-site.example --authorized [--deep] [--crawl]` | ترويسات الأمان، الكوكيز، CSP، TLS، تحليل الصفحة وبصمة المنصّة؛ `--deep` للمسارات المكشوفة و`--crawl` لزحف الصفحات |
536
+
537
+ القواعد المدمجة تغطي: Python، JavaScript/TypeScript، Dart/Flutter، Java/Kotlin، Go، PHP، Ruby، C#، C/C++،
538
+ Shell، Dockerfile، docker-compose، GitHub Actions، AndroidManifest، iOS plist، وملفات الإعدادات.
539
+
540
+ فئات الثغرات: أسرار ومفاتيح مضمّنة، تنفيذ أوامر/كود (RCE)، حقن SQL/XSS/قوالب/مسارات، فك تسلسل غير آمن،
541
+ تشفير ضعيف وتعطيل TLS، إعدادات خطرة (debug، CORS، 0.0.0.0)، أمان الموبايل، أمان الحاويات و CI،
542
+ سلامة الذاكرة في C، تسجيل بيانات حساسة، وملفات لا يجوز شحنها (.env، مفاتيح SSH، قواعد بيانات).
543
+
544
+ ### الجديد في 1.0
545
+
546
+ - **إصلاح تلقائي** (`--fix` و`--fix-dry-run`) لـ 39 قاعدة (38 تلقائيًا)، لا يُعرض إلا بعد التأكد أن الملف المعدَّل سليم
547
+ وأن القاعدة لم تعد تنطبق؛ ويظهر الفرق في الواجهة والتقارير وSARIF والمحرر.
548
+ - **تحليل التبعيات مع قابلية الوصول:** 23 نوعًا من ملفات التبعيات والقفل، ولكل ثغرة معروفة (OSV.dev) هل يستورد الكود
549
+ الحزمة وهل يستدعي الدالة المصابة.
550
+ - **الأسرار في تاريخ git** (`kashif history`)، و**الفرز داخل المستودع** (`kashif triage`)، و**السياسة ككود**
551
+ (`kashif.yml`)، و**الامتثال** لعشرة أطر مع تقرير للمدقق (`kashif compliance`)، و**خريطة سطح الهجوم** (`kashif surface`)،
552
+ و**عُدّة كتابة القواعد** (`kashif rules`).
553
+ - **خادم MCP** (`kashif mcp`) يتيح لـ Claude Code وCursor ووكلاء VS Code وWindsurf وZed فحص الكود الذي يكتبونه محليًا.
554
+ - **التصدير:** DefectDojo وSonarQube وGitLab SAST وCode Climate وJUnit وCSV وJira وGitHub Issues وAWS Security Hub (ASFF)
555
+ وOCSF.
556
+ - **إنذارات كاذبة أقل:** كود الاختبارات والتوثيق والأمثلة يُعرف من مساره فتُحذف منه نتائج بيانات الاختبار وتُخفَّض البقية
557
+ إلى info، ويُتخطّى الكود المضمَّن من مكتبات خارجية. في 35 مشروعًا مفتوح المصدر (من 38) كان 0.9 يُنهي فحصها، نزلت النتائج
558
+ من 17,228 إلى 2,607 (الحرجة والعالية من 4,345 إلى 783)، وكان نصف نتائج 0.9 في كود الاختبارات والتوثيق والأمثلة.
559
+ - **أسرع:** `--jobs N` لتوزيع الفحص على المعالجات، و`--cache DIR` لإعادة فحص مشروع لم يتغير بالنتائج نفسها: Django كاملًا
560
+ (6,973 ملفًا) في 311–411 ثانية أول مرة على 4 معالجات افتراضية (كان 594 ثانية في 0.9)، و3.5 ثوانٍ عند الإعادة.
561
+ - النماذج **6,357** واجهة مكتبة (مصادر 1,044، ونقاط خطر 4,532، ومعقّمات 781). التفاصيل في `CHANGELOG.md`.
562
+
563
+ ### فحص المواقع السلبي
564
+
565
+ يقرأ `kashif https://my-site.example --authorized` ما يقدّمه الموقع أصلًا كما يقرؤه المتصفح، ويحكم عليه بـ 184 قاعدة
566
+ (34 منها من الإصدار 1.0 بالمعرّفات نفسها، و150 جديدة): النقل وHSTS، وسياسة CSP، وحماية الإطارات وبقية ترويسات الاستجابة،
567
+ وCORS، والكوكيز، ومحتوى الصفحة وسكربتاتها، وتسرّب المعلومات، وTLS والشهادات، والمكوّنات (بيانات retire.js)، والملفات
568
+ المكشوفة و`security.txt`. لا يرسل أي حمولة، ولا يملأ نموذجًا، ولا يخمّن أو يجرّب مسارات عشوائية، ولا يزوّر الترويسات،
569
+ ويعرّف نفسه بصدق (`Kashif/<الإصدار>`) ويترك `--delay` ثانية على الأقل (والحد الأدنى 0.2) بين طلبين إلى المضيف نفسه.
570
+
571
+ ```bash
572
+ kashif https://my-site.example --authorized # نمط الفحص standard (45 طلبًا على الأكثر)
573
+ kashif https://my-site.example --authorized --web-profile minimal # الصفحة وتوجيهاتها فقط (10 طلبات على الأكثر)
574
+ kashif https://my-site.example --authorized --deep # مع الملفات المكشوفة الشائعة (150 طلبًا على الأكثر)
575
+ kashif https://my-site.example --authorized --crawl --max-pages 50 # مع صفحات الأصل نفسه (المخطط والمضيف والمنفذ)
576
+ kashif https://my-site.example --authorized --web-sensitivity strict -f sarif -o web.sarif
577
+ kashif https://my-site.example --authorized --compare-previous # مقارنة بآخر فحص محفوظ للموقع
578
+ kashif https://my-site.example --authorized --compare old-report.json # أو معرّف فحص من السجل المحلي
579
+ kashif update-data --web # بيانات ويب أحدث من آخر إصدار
580
+ ```
581
+
582
+ | الخيار | معناه |
583
+ |---|---|
584
+ | `--web-profile minimal\|standard\|deep` | `minimal` هو طلب الإصدار 1.0 الواحد (الصفحة وتوجيهاتها، 10 طلبات على الأكثر)؛ و`standard` (الافتراضي) يضيف نسخة http/https وطلب CORS واحدًا بلا كوكيز والملفين `robots.txt` و`security.txt` والأيقونة و`/sitemap.xml` (مع `--crawl`) وحتى 15 من سكربتات الصفحة وأنماطها (45 طلبًا على الأكثر)؛ و`deep` (أو `--deep`) يضيف قائمة ثابتة من الملفات المكشوفة الشائعة، وصفحات الدخول والإدارة للمنصّة المكتشفة (تُطلب مرة واحدة دون إرسال أي بيانات)، وخطوط أساس لصفحات 404، وسكربتات الأطراف الثالثة وخرائط المصدر والصور (150 طلبًا على الأكثر). وصفحات الزحف إضافة على ذلك. |
585
+ | `--web-sensitivity strict\|default\|paranoid` | `strict` النتائج المؤكَّدة فقط، و`default` المؤكَّدة والمرجَّحة، و`paranoid` كل شيء مع الفحوص الخاصة بهذا المستوى. وكل نتيجة تحمل درجة ثقتها (مؤكَّدة أو مرجَّحة أو محتملة). |
586
+ | `--crawl` و`--max-pages N` و`--max-depth N` و`--ignore-robots` | زحف بالعرض أولًا على روابط الأصل نفسه (المخطط والمضيف والمنفذ أنفسها)، بحدّ أعلى 500 صفحة (الافتراضي 20 صفحةً بعمق 2)؛ ويُحترم `robots.txt` إلا إن كنت مالك الموقع وأضفت `--ignore-robots`. ويحتاج إلى `standard` أو `deep`، فلا زحف في `minimal`. ويتوقف الفحص عن الإرسال بعد 600 ثانية أو بعد استقبال 50 ميغابايت. |
587
+ | `--compare-previous` و`--compare ID\|FILE` | النتائج الجديدة والمحلولة والثابتة، وتغيّر الدرجات وتغييرات الوضع الأمني («تغيّرت سياسة CSP»، «مضيف سكربتات جديد»، «جُدّدت الشهادة»). يحفظ `--compare-previous` الفحص في السجل المحلي (`~/.vulnscan` أو `$VULNSCAN_HOME`) ويطبع معرّفه على stderr، ويقبل `--compare` هذا المعرّف (ويظهر أيضًا في صفحة التقارير في الواجهة وفي `$VULNSCAN_HOME/index.json`) أو تقرير JSON (`-f json`). وفي CI استعمل `--compare previous.json`. ولا علاقة لـ `kashif history` بذلك (فهو يبحث في سجل git عن الأسرار). |
588
+ | `--fail-on-inconclusive` | رمز الخروج 1 إذا أجاب جدار حماية أو تحدٍّ أو تقييد معدل بدل الموقع (درجة كاشِف `?` أو النتيجة WEB990)، وهو ما يمرّره `--fail-on` وحده. |
589
+ | `--ignore-rule ID` | استبعاد قاعدة ويب من التقرير ومن `--fail-on` (وتبقى الدرجات تحسبها). |
590
+ | `--web-cookie-ignore NAME` | استبعاد كوكي من فحوص الكوكيز (يمكن تكراره). |
591
+ | `--third-party-lookups` | السماح باستعلامات تكشف اسم الموقع لطرف ثالث؛ معطّلة افتراضيًا، ولا يجري أي فحص في الإصدار 1.1 استعلامًا كهذا (فقائمة HSTS preload وشفافية الشهادات من بيانات مضمّنة ومن الشهادة نفسها). |
592
+ | `--no-proxy` | عدم استخدام `HTTP(S)_PROXY`. ولا يدعم كاشِف إلا الوكيل من نوع `http://`، وأي إعداد آخر يوقف الفحص بخطأ في الوكيل (رمز الخروج 2، وقيمة `web.error.code` في تقرير JSON تبدأ بـ `proxy`) ولا يتصل مباشرةً خفية. وعبر الوكيل تُعدّ الفحوص المعتمدة على DNS «لم تُجرَ» ونتائج TLS «محتملة»، فلا تظهر إلا مع `--web-sensitivity paranoid`؛ ولتقييم TLS مباشرةً استعمل `--no-proxy` أو `NO_PROXY`. |
593
+
594
+ يعرض كل تقرير ثلاث درجات (درجة كاشِف للويب من A+ إلى F، ودرجة متوافقة مع MDN HTTP Observatory، ودرجة TLS متوافقة مع
595
+ SSL Labs دون اختبارات الهجوم التي لا يجريها كاشِف)، وجدول تغطية صادقًا (ناجح، فاشل، غير منطبق، لم يُجرَ، غير حاسم: الفحص
596
+ الذي لم يُجرَ لا يُعرض ناجحًا أبدًا)، وجرد الموقع (ترويسات الأمان وCSP والكوكيز وTLS والتقنيات والأطراف الثالثة)، وإصلاحات
597
+ جاهزة للنسخ لـ 18 منصةً (nginx وApache httpd وIIS وCaddy وExpress وNode.js وDjango وFlask وSpring وTomcat وASP.NET Core
598
+ وASP.NET وPHP وLaravel وSymfony وRails وCloudflare وF5 BIG-IP، والمنصّات المكتشفة أولًا)، ومع فحص سابق: المقارنة. وتحمل نتائج SARIF الخاصية `properties.precision` والوسوم `external/cwe/cwe-N` و`wstg:…`
599
+ و`asvs4:…` و`asvs5:…`، ويحمل تقرير JSON البيانات نفسها تحت المفتاح `web`. القواعد وربطها ودرجات خطورتها في
600
+ [docs/web-checks.md](docs/web-checks.md)، والطلبات والملفات والتقارير والترقية من 1.0 في [docs/web-scanning.md](docs/web-scanning.md).
601
+ وفي الواجهة الرسومية الخيارات نفسها في نموذج فحص الويب، وبطاقة الدرجات وجدول التغطية وتبويبات الجرد والإصلاحات والمقارنة.
602
+
603
+ **في CI** (المثال الكامل في [docs/web-scanning.md](docs/web-scanning.md#الاستخدام-في-ci)):
604
+ `kashif https://staging.example.com --authorized --fail-on high --fail-on-inconclusive -f sarif -o kashif-web.sarif`.
605
+ ورمز الخروج 0 يعني نجاح البوابة، و1 فشلها (نتيجة بخطورة `--fail-on` أو أعلى، أو بوابة السياسة، أو فحص غير حاسم مع
606
+ `--fail-on-inconclusive`)، و2 أنه لم يُحكم على شيء (غياب `--authorized`، أو توليفة خيارات مرفوضة، أو تعذّر الوصول إلى
607
+ الموقع؛ ويكتب `-o` حينها تقريرًا مع ذلك قيمة `web.status` فيه `"unreachable"`). ارفع SARIF بالإجراء
608
+ `github/codeql-action/upload-sarif` مع `category: kashif-web` حتى لا يحلّ محل نتائج فحص الكود؛ وموضع إنذارات الويب عنوان
609
+ URL لا ملف، فلا تظهر تعليقاتٍ على أسطر طلب الدمج. واحتفظ بتقرير JSON من كل تشغيل ومرّره إلى التالي بـ
610
+ `--compare previous.json` لرؤية التراجعات.
611
+
612
+ **ملف السياسة:** مع عنوان ويب مرّر الملف صراحةً (`--policy kashif.yml`)، فلا يُلتقط أي ملف تلقائيًا. و`rules.disable`
613
+ و`rules.severity` تغيّران ما تحسبه البوابة لا التقرير (ولإخفاء قاعدة من التقرير استعمل `--ignore-rule`)، والبوابة
614
+ الافتراضية تفشل عند `high`، فاضبط `gate.fail_on`:
615
+
616
+ ```yaml
617
+ version: 1
618
+ gate:
619
+ fail_on: medium # البوابة الافتراضية تفشل عند high
620
+ rules:
621
+ disable:
622
+ - id: WEB071
623
+ reason: "certificates are renewed automatically 30 days before expiry"
624
+ ```
625
+
626
+ **ما لا يكشفه الفحص السلبي:** يقرأ الصفحات العامة فقط، ولا يختبر الحقن ولا XSS ولا المصادقة ولا التحكم في الوصول ولا
627
+ منطق العمل، ولا يتحقق من إلغاء الشهادة (CRL/OCSP). والدرجة تقيس سلامة الإعدادات لا خلوّ الموقع من الثغرات: فاجمع فحص الويب
628
+ مع فحص الكود (SAST) ومع اختبار نشط مصرَّح به.
629
+
630
+ > ⚠️ كل فحص ويب يتطلب `--authorized` (أو تفعيل الإقرار في الواجهة). افحص فقط المواقع التي تملكها أو لديك
631
+ > تصريح كتابي بفحصها.
632
+
633
+ ### تحليل تدفق البيانات (Taint) — محرّك مدرك للأنواع على نهج CodeQL
634
+
635
+ إضافةً إلى قواعد الأنماط، يبني كاشِف **نموذجًا واحدًا للمشروع كله** ويتتبّع البيانات من المصادر غير الموثوقة إلى
636
+ نقاط الخطر عبر الدوال والأصناف والملفات. ما يجعله قريبًا من CodeQL:
637
+
638
+ | القدرة | كيف تعمل في كاشِف |
639
+ |---|---|
640
+ | **نماذج كبيانات (Models-as-Data)** | المصادر ونقاط الخطر والمُعقّمات ونقاط الدخول والمدقّقات مُعرَّفة في JSON (`vulnscan/models/python.json`). أضف نماذج مكتباتك بـ `--models DIR` أو من الإعدادات دون تعديل الكود. |
641
+ | **نماذج مكتبات مدمجة** | Flask/Django/FastAPI/Starlette/Tornado/aiohttp كمصادر ونقاط دخول؛ نقاط خطر لـ `os`/`subprocess`/SQL (`execute`، `raw`، `sqlalchemy.text`)/الملفات/`pickle`/`yaml`/القوالب/`redirect`/**SSRF** (`requests`، `urlopen`، `httpx`)/عمليات نظام الملفات/الاستيراد الديناميكي/XSS الانعكاسي/LDAP/XPath/حقن السجلات. 16 قاعدة `DF001`–`DF016`. |
642
+ | **نقاط دخول أطر العمل** | معاملات الدوال المُوجَّهة (`@app.route`، `@router.get`، views بالأصناف، أوامر CLI) مصادر تلقائيًا، كما في RemoteFlowSource. |
643
+ | **حلّ استدعاءات مدرك للأنواع** | نوع المتغير من المُنشئ والتعليقات و`self` والحقول وأنواع الإرجاع؛ حلّ الدوال عبر MRO مع التعدد الشكلي؛ تتبّع قيم الدوال (`h = helper`، `functools.partial`) و`*args`/`**kwargs`؛ والاستيرادات المطلقة والنسبية والمستعارة (`import subprocess as sp`). |
644
+ | **حساسية الحقول والحاويات** | `self.x` بين الدوال، وسائط المُنشئ إلى الحقول، `append`/التخزين بالفهرس/القوائم الحرفية. |
645
+ | **points-to حسّاس للسياق (k=2) وحسّاس للتدفق** | تحليل Andersen بسلسلة استدعاء بعمق اثنين واستنساخ الكائنات، فالمصنع المستدعى من موضعين يعيد كائنين مختلفين حتى عبر غلاف وسيط؛ والمتغيرات المحلية بصيغة SSA (تحديث قوي، ودمج الفروع، وحلقات بنقاط φ) فإعادة الإسناد تلغي التلوّث السابق. |
646
+ | **حواجز التحقق (path-sensitivity)** | `if x in ALLOWED:`، `x.isalnum()`، `re.fullmatch(..، x)`، و`if not valid(x): return` تمنع الإبلاغ عن النقطة المحروسة، داخل الدالة وعبر الدوال المساعدة. |
647
+ | **مسار التدفق الكامل** | كل نتيجة تحمل خطوات المسار من المصدر إلى نقطة الخطر عبر الإسنادات والاستدعاءات والملفات، وتُعرض في الواجهة والتقارير. |
648
+ | **دقة التصنيف** | عنصر ملوّث داخل قائمة وسائط بعد برنامج ثابت وبلا `shell=True` = حقن وسائط (`DF009`، متوسط) لا حقن أوامر (`DF003`)؛ `getoutput`/`os.system` بسلاسل shell = حرج. |
649
+ | **كتم مراجَع** | `# nosec` على سطر نقطة الخطر يكتم النتيجة وكل ما يُشتق منها في المستدعين. |
650
+
651
+ ```python
652
+ # io_mod.py
653
+ def read_name(): return request.args["name"] # يعيد بيانات غير موثوقة
654
+ # exec_mod.py
655
+ def run(cmd): os.system(cmd) # وسيط يصل إلى نقطة خطر
656
+ # views.py
657
+ @app.route("/x")
658
+ def handler(): run(read_name()) # ← يُبلَّغ عنه مع مسار: io_mod.py:2 → views.py:3 → exec_mod.py:2
659
+ ```
660
+
661
+ مثال على نموذج مستخدم (`my_models.json`):
662
+
663
+ ```json
664
+ {"sinks": [{"rule": "DF901", "severity": "high", "cwe": "CWE-999", "label": "mylib.dangerous",
665
+ "names": ["mylib.dangerous"], "title": "custom sink", "title_ar": "نقطة خطر مخصصة",
666
+ "advice": "لا تمرّر مدخلات المستخدم.", "args": [0]}],
667
+ "sanitizers": ["mylib.clean"]}
668
+ ```
669
+
670
+ ما يبقى مختلفًا عن CodeQL بصدق: لا نمذجة كاملة للمكتبة المعيارية لكل لغة (النماذج تغطي الأطر الشائعة لا كل واجهة)،
671
+ ولا تكامل IDE/مراجعة الطلبات، وواجهات اللغات غير Python تحليلية متسامحة — لكنها الآن **تُبلّغ عن كل عبارة تخطّتها**
672
+ (سطرها وسببها في ملاحظات الفحص) فلا يسقط شيء بصمت. القيود الأربع التي كانت قائمة أُغلقت: صار points-to حسّاسًا للسياق
673
+ بعمق اثنين وحسّاسًا للتدفق، وصارت VQL تدعم الأصناف والمسندات الذاتية والتجميعات، وصار المحرّك يغطّي 12 لغة.
674
+
675
+ ### تحليل points-to (تحليل المؤشّرات)
676
+
677
+ فوق استنتاج الأنواع، يُجري المحرّك تحليل **points-to على نهج Andersen، حسّاسًا لموضع الاستدعاء (k = 1) مع استنساخ
678
+ الكائنات لكل سياق** (`vulnscan/pointsto.py`): كل استدعاء مُنشئ
679
+ وكل قائمة/قاموس حرفي وكل دالة كقيمة **كائن مجرّد** بموضع تخصيصه (allocation site)؛ والمتغيرات وحقول الكائنات
680
+ وعناصر الحاويات وقيم الإرجاع **عقد مؤشّرات**؛ والإسنادات وقراءة/كتابة الحقول والاستدعاءات (وسيط ← معامل، إرجاع ← نتيجة،
681
+ متلقٍّ ← `self`) والتكرار تولّد قيود احتواء تُحلّ حتى نقطة الثبات. يستفيد منه المحرّك في:
682
+
683
+ - **حلّ الاستدعاءات على الكائنات الفعلية** لا على النوع الساكن فقط: دوال مُمرَّرة كمعاملات (callbacks)، دوال
684
+ تُعاد من مصانع، كائنات محفوظة في قواميس أو قوائم (`HANDLERS["sh"].run(...)`).
685
+ - **التسمية المستعارة في الذاكرة (heap aliasing)**: تلوّث يُخزَّن في حقل كائن يظهر عبر كل أسمائه المستعارة في أي دالة،
686
+ حتى عبر المتغيرات العامة والحاويات (`STORE.append(t)` في دالة، و`os.system(t.cmd)` في أخرى).
687
+ - **فصل مواضع التخصيص**: `Task()` ملوّثة في دالة و`Task()` نظيفة في أخرى تبقيان كائنين مختلفين.
688
+
689
+ - **حساسية السياق**: تُستنسخ عقد الدالة وكائناتها لكل موضع استدعاء (k = 1)، فمصنع يُستدعى من موضعين يُعيد كائنين
690
+ مختلفين، وcallback مُمرَّر كمعامل يُحلّ **لكل موضع استدعاء على حدة**: `run_all(shell, t)` تُبلَّغ و`run_all(logger, t)`
691
+ لا تُبلَّغ، بدل اتحاد كل الدوال التي مرّت يومًا عبر ذلك المعامل.
692
+
693
+ التحليل غير حسّاس للتدفق، وحساسيته للسياق بعمق استدعاء واحد (k = 1) مع حدّ أقصى للسياقات لكل دالة حفاظًا على
694
+ الزمن، بينما تبقى حساسية السياق لتدفق التلوّث نفسه عبر ملخّصات الدوال، فتُبلَّغ النتيجة في موضع الاستدعاء الملوّث.
695
+
696
+ ### 12 لغة بنفس محرّك تدفق البيانات: Python، JavaScript/TypeScript، Java، Kotlin، C#، Go، PHP، C/C++، Rust، Swift، Ruby، PL/SQL
697
+
698
+ المحرّك يعمل على **شكل** البرنامج لا على لغته، لذا تدعم الأداة JavaScript وTypeScript عبر واجهة أمامية
699
+ (`vulnscan/js_frontend.py`) تحلّل الكود بمحلّل متسامح خاص بها (بلا أي اعتمادية) وتُنزّله إلى الشجرة نفسها
700
+ التي يفهمها المحرّك، فتحصل تلقائيًا على كل ما سبق: إدراك الأنواع، عبر الملفات، الحقول، حواجز التحقق، ومسار التدفق.
701
+
702
+ - **ما يُفهم**: ES2020+ (الاستيراد والتصدير و`require`، الأسهم، القوالب النصية، التفكيك، الأصناف، `async/await`،
703
+ التسلسل الاختياري) وTypeScript (التعليقات النوعية تُتجاهل، والمُزخرِفات وخصائص معاملات المُنشئ تُحفظ،
704
+ و`interface/type/enum` تُتخطّى).
705
+ - **نماذج Node والمتصفح** في `vulnscan/models/javascript.json`: مصادر Express/Koa/Lambda (`req.query/body/params`،
706
+ `event`، `process.argv`، `location`، `document.cookie`)، ونقاط دخول (`app.get(...)`، NestJS `@Get()`،
707
+ `exports.handler`)، ونقاط خطر `child_process`، `fs`، `res.send`، `innerHTML`، `axios/fetch` (SSRF)، `res.redirect`،
708
+ `require` الديناميكي، قوالب EJS/Pug/Handlebars، واستعلامات `query/raw/$queryRawUnsafe`.
709
+ - أسماء الاستيراد تُحلّ (`const cp = require('child_process')` فيُفهم `cp.exec`)، والملفات النسبية
710
+ (`require('./lib/shell')`) تُربط عبر المشروع.
711
+ - الملفات المضغوطة (`*.min.js`) وتعريفات الأنواع (`*.d.ts`) والحزم الضخمة تُتخطّى.
712
+ - **Java وKotlin وC# وGo وPHP** عبر واجهة أمامية لعائلة C (`vulnscan/cfamily_frontend.py`) بالمنهج نفسه: دوال
713
+ وأصناف وحقول (مع `this` الضمني في Java/Kotlin/C#)، الاستيرادات (`import`/`using`/`use`/حزم Go)، المُزخرِفات
714
+ والسمات (`@GetMapping`، `[HttpGet]`، `#[Route]`)، الاستيفاء النصي (`"$x"`، `$"{x}"`)، معاملات مُنشئ Kotlin
715
+ كحقول مُعنوَنة، أساليب المستقبِل في Go، والمتغيرات الفائقة في PHP. نماذج لكل لغة في `vulnscan/models/`
716
+ (Servlet/Spring/JDBC، Ktor/Spring، ASP.NET/EF، net/http/gin/database/sql، PDO/mysqli/Laravel/Symfony).
717
+
718
+ ```js
719
+ // lib/shell.js
720
+ const cp = require('child_process');
721
+ function run(c) { cp.execSync(c); } // وسيط يصل إلى أمر shell
722
+ module.exports = { run };
723
+ // server.js
724
+ const { run } = require('./lib/shell');
725
+ app.post('/x', (req, res) => { run(req.body.c); }); // ← يُبلَّغ عنه عبر الملفين
726
+ ```
727
+
728
+ ### Oracle APEX وPL/SQL والمساعد الذكي
729
+
730
+ يفحص كاشِف كود قاعدة بيانات Oracle وتطبيقات APEX من المصدر، لا من الموقع فقط. ضع ملفات التصدير والحزم في مجلد وافحصه:
731
+
732
+ ```
733
+ kashif ./my-apex-app # f100.sql أو application/pages/*.sql، وملفات .pkb/.pks/.sql/.trg
734
+ ```
735
+
736
+ | ما يُحلَّل | كيف |
737
+ |---|---|
738
+ | **PL/SQL** (`.sql` `.pkb` `.pks` `.pls` `.prc` `.fnc` `.trg` …) | الحزم والإجراءات والدوال والمشغّلات والكتل المجهولة، بتحليل تدفق البيانات نفسه عبر الحزم والملفات، مع الوسائط المسمّاة `p_x => v`. |
739
+ | **ملف تصدير APEX** (تطبيق كامل أو صفحة أو إضافة) | يُستخرج كل كود من داخل استدعاءات `wwv_flow_imp_page.create_…`: العمليات، ومناطق PL/SQL، و"دالة تُعيد استعلام SQL"، والتحققات والحسابات والشروط، والإجراءات الديناميكية، ورمز الإضافات، وملفات JavaScript المضمّنة بالترميز الست عشري. كل نتيجة تشير إلى سطرها في ملف التصدير وإلى مكوّنها: «صفحة 10 › عملية: Save». |
740
+ | **تصدير APEX المقروء (YAML)** | مجلد `readable/` (APEX 23.2+): تُقرأ الخصائص النصية (`pl/sql-code`، `sql-query`، `pl/sql-function-body-returning-sql-query`، كود JavaScript، تعليمات الذكاء الاصطناعي) من سطرها، وتُنسب إلى المكوّن من عناوين `# ====== Region: …`، ويُكشف `escape-special-characters: false`. |
741
+ | **معالجات ORDS** | `ORDS.DEFINE_HANDLER` / `DEFINE_SERVICE` حيثما وُجدت: في `.sql`، وداخل سجلات Liquibase/SQLcl بصيغة XML (`runOracleScript` و CDATA)، وفي تعريفات REST بصيغة JSON. معالجات PL/SQL تُحلَّل ككود، ومعالجات الاستعلام كـ SQL، ومتغيرات الربط (`:id` و`:body_text`…) مصادر، و`:forward_location` نقطة تحويل. |
742
+ | **دوال داخل SQL الثابت** | الاستعلامات الثابتة في التقارير وقوائم القيم ومعالجات ORDS، وجمل `SELECT/INSERT/UPDATE/DELETE/MERGE` والمؤشرات داخل PL/SQL: متغير الربط آمن لـ SQL، لكن الدالة التي تستقبله تُتتبَّع، فإن بنت به SQL ديناميكيًا يُبلَّغ عنه. |
743
+ | **Java داخل قاعدة البيانات** | كتل `create … java source` تُحلَّل بواجهة Java، و«call spec» (`as language java name '…'`) يُربط بالدالة، فيُكشف التدفق من عنصر الصفحة عبر PL/SQL إلى `Runtime.exec` في Java. |
744
+
745
+ **المصادر**: عناصر الصفحة `:P1_X` و`v('P1_X')` و`nv()` و`apex_util.get_session_state()`، و`apex_application.g_x01…g_f50`، وقيم الإضافات `p_item.value` و`p_param.value`، و`owa_util.get_cgi_env` و`apex_json`.
746
+ **نقاط الخطر**: `EXECUTE IMMEDIATE` و`OPEN … FOR` و`DBMS_SQL.PARSE` و`apex_exec` و`apex_collection.create_collection_from_query`، و`htp.p`، و`owa_util.redirect_url`، و`apex_web_service`/`utl_http`، و`utl_file`، و`dbms_ldap`، و`dbms_scheduler`/`dbms_job`.
747
+ **المعقّمات**: `USING` (متغيرات الربط) و`DBMS_ASSERT` و`apex_escape` و`htf.escape_sc`.
748
+
749
+ قواعد خاصة بـ APEX لا تحتاج تدفق بيانات:
750
+
751
+ | القاعدة | المشكلة |
752
+ |---|---|
753
+ | `APX001` | سلسلة استبدال `&P1_X.` داخل SQL أو PL/SQL — تُستبدل نصيًا قبل التنفيذ فتسمح بالحقن. |
754
+ | `APX002` | `&P1_X.` داخل JavaScript دون المرشّح `!JS`. |
755
+ | `APX003` | `&P1_X!RAW.` في HTML. |
756
+ | `APX004` | تهريب المخرجات معطّل لعمود أو عنصر (`WITHOUT_MODIFICATION`). |
757
+ | `APX005` | عنصر يتحكم به المستخدم يُستبدل داخل تعليمات المساعد الذكي (إعداد AI في APEX 24). |
758
+
759
+ **فحص إعدادات أمان التطبيق** (على نهج APEX Advisor وAPEX-SERT، من ملف التصدير بصيغتيه SQL وYAML):
760
+
761
+ | القاعدة | الإعداد |
762
+ |---|---|
763
+ | `APX006` | حماية حالة الجلسة (Session State Protection) معطّلة |
764
+ | `APX007` | Rejoin Sessions لكل الجلسات |
765
+ | `APX008` | السماح بالتضمين في إطار من أي موقع |
766
+ | `APX009` | روابط تعديل المطوّر في بيئة التشغيل |
767
+ | `APX010` | checksum بـ MD5/SHA1 |
768
+ | `APX011` | تهريب HTML أساسي |
769
+ | `APX012` | Runtime API تعدّل التطبيقات |
770
+ | `APX013` | كوكي المصادقة دون Secure |
771
+ | `APX014` | مخطط «بلا مصادقة» |
772
+ | `APX015` | كلمة مرور تُقارن كنص صريح (المصادقة المخصصة والحزم) |
773
+ | `APX016` | صفحة عامة تعدّل البيانات (تُستثنى عمليات صفحة الدخول التي لا تكتب في الجداول) |
774
+ | `APX017` | صفحة تعدّل البيانات بلا مخطط تفويض |
775
+ | `APX018` | حماية الوصول للصفحة غير مقيّدة |
776
+ | `APX019` | عنصر مخفي قيمته غير محمية |
777
+ | `APX020` | عملية AJAX عند الطلب بلا تفويض |
778
+ | `APX021` | الاستبدال دون النقطة الختامية |
779
+ | `APX022` | وحدة PL/SQL ملفوفة (wrapped): تُذكر مرة واحدة ولا يُفحص نصّها (معلوماتية) |
780
+ | `APX023` | إضافة (Plug-in) معرَّفة لا يستخدمها أي مكوّن في التطبيق؛ وتُخفَّض خطورة ما يوجد داخلها درجة واحدة |
781
+
782
+ أسماء الخصائص ومعانيها مأخوذة من ملفات تصدير أوراكل الرسمية نفسها، وقد جُرّبت الفحوص عليها.
783
+
784
+ **ثغرات المساعد الذكي** (`apex_ai` و`dbms_cloud_ai` / Select AI و`dbms_vector_chain`):
785
+
786
+ | القاعدة | المشكلة |
787
+ |---|---|
788
+ | `DF019` | بيانات المستخدم تصل إلى `p_system_prompt` — حقن التعليمات. |
789
+ | `DF020` حرج | نص يولّده النموذج يُنفَّذ كـ SQL أو كود (`execute immediate` على مخرجات `apex_ai.generate`). |
790
+ | `DF021` | مخرجات النموذج تُكتب في الصفحة دون تهريب (XSS عبر النموذج). |
791
+ | `DF022` | نص المستخدم يقود توليد SQL عبر Select AI — يُنبّه لتقييد ملف التعريف وصلاحيات التنفيذ. |
792
+
793
+ **الحقن من الدرجة الثانية وXSS المخزّن** (`DF023` و`DF024`): يتتبّع كاشِف الجداول نفسها. حين يكتب `INSERT` أو `UPDATE`
794
+ أو `INSERT … SELECT`، أو نموذج APEX يحفظ عناصره تلقائيًا (Form Region / Automatic Row Processing)، قيمةً من المستخدم في
795
+ `جدول.عمود`، تصير كل قراءة لذلك العمود (`SELECT … INTO`، وحقول صفوف حلقات المؤشر، و`FETCH`) مصدرًا ملوّثًا في أي ملف.
796
+ يُعاد التحليل حتى الاستقرار فتُتبع النُسخ من جدول إلى آخر. الأعمدة التي لا يكتب فيها المستخدم لا تُبلَّغ عنها، والنتيجة
797
+ تذكر أين كُتبت القيمة: «بيانات مخزّنة في NOTES.BODY (كتبها مستخدم في f300.sql:19)».
798
+
799
+ **تعريفات REST بصيغة JSON**: تُقرأ صيغتان معروفتان: الوحدة المتداخلة (`templates` → `handlers`)، وتصدير جداول ORDS الوصفية
800
+ (`USER_ORDS_MODULES` و`_TEMPLATES` و`_HANDLERS`، كما يصدّرها SQL Developer) مع ربط المعالج بنمطه ووحدته عبر المعرّفات.
801
+ وفي أي ملف JSON آخر، كل قيمة نصية هي كتلة PL/SQL كاملة (`begin … ; … end;`) تُحلَّل ككود أيًّا كان اسم مفتاحها،
802
+ وتُنسب النتيجة إلى مسارها داخل الملف (`JSON › $.steps[0].plsqlBody`).
803
+
804
+ ### الحقن من الدرجة الثانية في كل اللغات
805
+
806
+ الآلية نفسها (الكتابة في `جدول.عمود` ثم قراءته مصدرًا) تعمل على كل اللغات، لأنها تجري على الشجرة المشتركة بعد الواجهات الأمامية:
807
+
808
+ | النوع | ما يُفهم |
809
+ |---|---|
810
+ | **SQL خام بمتغيرات ربط** | `?` و`%s` و`%(name)s` و`$1` و`:name` و`@name`: `cur.execute(sql, params)`، `db.query(sql, [..])`، `db.Exec(sql, a)`، JDBC `prepareStatement` + `setString(1, x)` + `executeQuery`/`ResultSet`، PDO `prepare` + `execute([..])`/`bindParam`، mysqli `bind_param`، ADO.NET `SqlCommand` + `Parameters.AddWithValue`، `db.prepare(sql).run(a)`، و`row.Scan(&x)` في Go. |
811
+ | **ORM** | Django وSQLAlchemy وPeewee وSQLModel، وActiveRecord، وMongoose وSequelize وPrisma وTypeORM، وJPA/Hibernate (`@Entity` مع setters/getters ومستودعات Spring Data بالاسم). الكتابة: `create`/`update`/المُنشئ/`obj.f = x`/`setF(x)`؛ القراءة: حقول الكائن المجلوب أو متغير الحلقة. |
812
+
813
+ ما يعود من قاعدة البيانات يحمل تلوّث الأعمدة فقط، لا تلوّث مفتاح البحث: `Msg.findById(req.params.id).who` ليس ملوّثًا إلا إن كتب
814
+ مستخدمٌ في `MSG.WHO`.
815
+
816
+ **أسماء الجداول الحقيقية**: يُحسب جدول كل صنف ORM كما يحسبه إطاره: `__tablename__` (SQLAlchemy)، و`Meta.db_table` أو
817
+ `<app>_<model>` الافتراضي (Django)، و`self.table_name` (Rails)، و`@Table(name=…)`/`@Entity("…")` (JPA/TypeORM)، ومجموعة
818
+ Mongoose في الوسيط الثالث، و`tableName` في Sequelize. ثم تُوحَّد كل الأسماء بصيغة قانونية (بلا مخطط، مفرد، وأسماء الأعمدة بلا
819
+ شرطات: `created_at` = `createdAt`)، فجدول `notes` في SQL الخام وصنف `Note` في ORM جدول واحد.
820
+
821
+ **الدوال الوسيطة العامة**: دالة تأخذ الجدول أو الصنف والبيانات كوسائط، مثل `save(table, data)` التي تبني
822
+ `INSERT INTO {table}`، أو `create(Model, **fields)`، أو `createRecord(Model, data)`، أو `fetch(table, id)`، تُكتشف تلقائيًا،
823
+ وتُنمذج الكتابة والقراءة عند كل استدعاء بالجدول والمفاتيح الفعلية. ومفاتيح قاموس حرفي ثابت لا تُعدّ مدخلات مستخدم،
824
+ أما مفاتيح `request.form` فتبقى ملوّثة.
825
+
826
+ **نصوص SQL غير الحرفية**: يُقيَّم نص الاستعلام قبل تحليله: الثوابت على مستوى المشروع، و`q += …` المتتابعة، و`format`
827
+ و`%` و`join` والقوالب النصية، ودوال المشروع التي تبني الاستعلام من وسائطها. واسم الجدول المقروء من الإعدادات يُحلّ من
828
+ ملفات المشروع: `.env` و`.ini`/`.cfg` و`.properties` و`.json` و`.yaml` و`.toml`، عبر `os.getenv` و`os.environ` و`process.env`
829
+ و`settings.X` و`config["a"]["b"]` و`ENV[...]` و`System.getenv` و`@Value("${…}")` في Spring.
830
+ وتُقرأ متغيرات البيئة من ملفات النشر أيضًا: `Dockerfile` و`docker-compose` وKubernetes وHelm وGitHub Actions و`app.json`.
831
+ والقيمة المعرّفة في ملفات المشروع إعدادٌ يتحكم به المشغّل فلا تُعامل كمدخل مستخدم، أما المتغير غير المعرّف فيبقى مصدرًا.
832
+
833
+ **جدول يُحدَّد وقت التشغيل**: حين لا يمكن معرفة الجدول من الملفات أصلًا (اسمه يُقرأ من القاعدة نفسها أو من خدمة خارجية)،
834
+ يُربط الحفظ بالقراءة عبر اسم العمود: كتابة المستخدم في العمود `COMMENT` لجدول مجهول تجعل قراءة `COMMENT` مصدرًا محتملًا.
835
+ تظهر هذه النتائج بخطورة أقل درجة وبوصف صريح «الجدول يُحدَّد وقت التشغيل (الربط باسم العمود)».
836
+
837
+ ### VQL — لغة استعلام فوق قاعدة بيانات البرنامج
838
+
839
+ على نهج `from … where … select` في CodeQL، تبني الأداة **قاعدة بيانات علاقية** للبرنامج (الاستدعاءات، الدوال،
840
+ الأصناف، الإسنادات، السلاسل، الاستيرادات، المُزخرِفات، السمات، **وتدفقات** محرّك التلوّث) وتشغّل عليها استعلامات
841
+ تصريحية. عشرة استعلامات مدمجة في `vulnscan/queries/` (منها: تعطيل التحقق من TLS، `yaml.load` بلا Loader، JWT ضعيف،
842
+ CORS بنجمة، نقطة دخول بلا مصادقة، عشوائية غير مشفّرة لسر، SQL مُركّب نصيًا)، وتضيف استعلاماتك بـ `--query DIR`:
843
+
844
+ ```
845
+ // @id vql/tls-verify-disabled
846
+ // @name TLS certificate verification disabled
847
+ // @severity high
848
+ // @cwe CWE-295
849
+ // @advice فعّل التحقق من الشهادة.
850
+ from call c
851
+ where c.name matches "^(requests|httpx)\." and c.kwargs contains "verify=False"
852
+ select c, "TLS verification disabled in " + c.name
853
+ ```
854
+
855
+ - **العلاقات**: `call` (name, func, receiver, args, arg0..arg3, kwargs, in_func, in_class…)، `func` (name, qual,
856
+ decorators, is_entry, is_method…)، `class`، `assign` (target, value)، `string`، `import`، `decorator`، `attr`،
857
+ و`flow` (rule, severity, source, callee, interprocedural, hops, sink_file, sink_line) لنتائج تدفق البيانات.
858
+ - **المعاملات**: `=` `!=` `<` `>` `<=` `>=` `matches` (regex) `contains` `in (…)` `and` `or` `not` والأقواس،
859
+ وربط عدة علاقات في `from` بشروط مساواة، و`+` لتركيب الرسالة.
860
+ - `kashif --list-rules .` يعرض الاستعلامات مع القواعد، وتظهر نتائجها بمصدر `vql`.
861
+
862
+ - **مسندات يعرّفها المستخدم مع استدعاء ذاتي** (Datalog): `predicate` بعدة فقرات تفصلها `or`، ومتغيرات حرّة
863
+ `value x` تُربط بالضمّ على صفوف المسند، وتقييم تصاعدي حتى نقطة الثبات، فتُكتب الإغلاقات المتعدية مباشرة:
864
+
865
+ ```
866
+ predicate calls(f, g) { from call c where c.in_func = f and c.func = g }
867
+ predicate reaches(f, g) { calls(f, g) or from value h where calls(f, h) and reaches(h, g) }
868
+ from func e where e.is_entry and reaches(e.name, "system") select e, "يصل إلى أمر shell"
869
+ ```
870
+
871
+ والاستعلام المدمج `vql/entry-reaches-shell` يستخدمها لرصد نقاط الدخول التي تصل إلى أوامر shell عبر مخطط
872
+ الاستدعاءات.
873
+
874
+ بصدق: VQL تدعم الآن الأصناف (بمسند مميِّز ومسندات أعضاء وجوالب) والمسندات الذاتية والتجميعات (count/strictcount/sum/max/min/avg وexists/any)؛ تبقى مجموعة عملية واسعة من QL دون نظام الوحدات/الاستيراد والأنواع المَعلَمة والمكتبة المعيارية الكاملة.
875
+
876
+ ### فحص تطبيقات الويب وصفحاتها (الزحف وبصمة المنصّات)
877
+
878
+ لفحص تطبيق ويب متعدد الصفحات مثل بوابة جامعة أو نظام **Moodle** أو تطبيق **Oracle APEX**، أضِف `--crawl`:
879
+ تتبع الأداة روابط الصفحات من **الأصل نفسه** (المخطط والمضيف والمنفذ أنفسها) زحفًا بالعرض (BFS) وتفحص كل صفحة بالفحوص السلبية.
880
+
881
+ ```bash
882
+ kashif https://lms.jamiah.example --authorized --crawl --deep
883
+ ```
884
+
885
+ - حدود الزحف: `--max-pages` (الافتراضي 20، والحد الأعلى 500) و`--max-depth` (الافتراضي 2). لا تُتبع روابط الخروج/الحذف
886
+ (logout، delete…) ولا الروابط الخارجة عن الأصل، ولا تُرسَل أي بيانات.
887
+ - **بصمة المنصّة**: تتعرّف الأداة تلقائيًا على Moodle وOracle APEX وWordPress وJoomla وDrupal وphpMyAdmin
888
+ وLaravel من الصفحة والترويسات، وتنبّه إذا كان الإصدار المكتشف به ثغرات معروفة (WEB800) أو انتهى دعمه (WEB801). ومع
889
+ `--deep` تجلب مرة واحدة بطلب GET عادي مسارات الإدارة والدخول المعروفة للمنصّة المكتشفة (مثل `/login/index.php`
890
+ و`/wp-login.php` و`/administrator/`) دون إرسال أي بيانات إليها، مع القائمة الثابتة من الملفات المكشوفة الشائعة.
891
+
892
+ > ⚠️ الزحف وفحص الويب يتطلبان `--authorized`. افحص فقط الأنظمة التي تملكها أو لديك تصريح كتابي بفحصها —
893
+ > فحص بوابة جامعة أو أي نظام لا تملكه دون إذن قد يكون مخالفًا للقانون.
894
+
895
+ ### فك تجميع APK / JAR / AAR / DEX (jadx)
896
+
897
+ إذا كان [jadx](https://github.com/skylot/jadx) مثبّتًا (يحتاج Java 11+)، تُفكّ تجميع الحزم الثنائية تلقائيًا
898
+ إلى كود Java مع فك ترميز `AndroidManifest.xml` والموارد، وتُطبَّق عليها كل القواعد (تنفيذ الأوامر، الأسرار،
899
+ التشفير الضعيف، WebView، cleartext…). تظهر هذه النتائج بمسار `app.apk!decompiled/…` وبعلامة `jadx`.
900
+
901
+ - مكتبات الطرف الثالث الشائعة (androidx، kotlin، okhttp، firebase…) تُستبعد افتراضيًا لتقليل الضجيج؛
902
+ فعّل فحصها بـ `--jadx-include-libs` أو من الإعدادات.
903
+ - بدون jadx تُفحص الملفات النصية داخل الحزمة فقط ويظهر تنبيه بذلك في التقرير.
904
+ - خيارات: `--no-jadx`، `--jadx-timeout SEC` (الافتراضي 600).
905
+
906
+ التثبيت: نزّل `jadx-x.y.z.zip` من صفحة الإصدارات وأضف مجلد `bin` إلى PATH، أو:
907
+ `brew install jadx` (macOS) · `scoop install jadx` / `choco install jadx` (Windows) · `sudo apt install jadx` (Debian/Ubuntu).
908
+
909
+ بالإضافة إلى ذلك، وعند توفر الإنترنت:
910
+ - **ثغرات الاعتماديات المعروفة (CVE)** عبر [OSV.dev](https://osv.dev) من `requirements.txt`،
911
+ `package-lock.json`، `package.json`، `pubspec.lock`، `go.mod`، `Gemfile.lock`، `composer.lock`.
912
+ - **دمج أدوات خارجية** إن كانت مثبّتة (اختياري تمامًا): `bandit`، `semgrep`، `gitleaks`، `npm audit`.
913
+
914
+ ## التثبيت
915
+
916
+ ```bash
917
+ pip install git+https://github.com/abdulrahmanahmedelabed-prog/vulnscan
918
+ ```
919
+
920
+ أو بدون تثبيت:
921
+
922
+ ```bash
923
+ git clone https://github.com/abdulrahmanahmedelabed-prog/vulnscan
924
+ cd vulnscan
925
+ python -m vulnscan /path/to/project
926
+ ```
927
+
928
+ ## التثبيت بسطر واحد (مع التحقق من SHA-256)
929
+
930
+ ```bash
931
+ # macOS ولينكس
932
+ curl -fsSL https://abdulrahmanahmedelabed-prog.github.io/vulnscan/install.sh | sh
933
+ # Homebrew
934
+ brew tap kashif/vulnscan https://github.com/abdulrahmanahmedelabed-prog/vulnscan && brew install kashif
935
+ ```
936
+
937
+ ```powershell
938
+ # ويندوز
939
+ irm https://abdulrahmanahmedelabed-prog.github.io/vulnscan/install.ps1 | iex
940
+ ```
941
+
942
+ تنزّل الطرق الثلاث النسخة الرسمية وتطابقها مع `SHA256SUMS.txt` قبل التثبيت، ولأنها تنزّل بـ curl فلا يضع macOS علامة
943
+ الحجر على الملف فلا يمنعه Gatekeeper.
944
+
945
+ ## داخل محرر الكود وطلبات الدمج
946
+
947
+ - **محرّرات الكود:** `kashif lsp` خادم لغة (LSP) يضع خطًا تحت الثغرات أثناء الكتابة مع مسار تدفق البيانات وطريقة
948
+ الإصلاح وإصلاحات سريعة (كتم نتيجة مُراجَعة أو إضافتها لخط الأساس). إضافة VS Code مرفقة بكل إصدار (`kashif-vscode.vsix`)،
949
+ ويعمل الخادم نفسه مع JetBrains وNeovim وHelix وZed وSublime وEmacs (الإعداد في `editors/README.md`).
950
+ - **طلبات الدمج:** إجراء GitHub يعلّق على الأسطر المتغيّرة فقط ويحدّث تعليق ملخّص واحد، و`--diff-base origin/main` لفحص ما
951
+ أضافه الفرع فقط، وتقارير GitLab (`-f gitlab-sast` و`-f codeclimate`)، وخطّاف pre-commit (الدليل في `docs/integrations.md`).
952
+
953
+ ## نسخ جاهزة (بلا تثبيت Python)
954
+
955
+ نزّل الملف من [صفحة الإصدارات](https://github.com/abdulrahmanahmedelabed-prog/vulnscan/releases/latest):
956
+
957
+ | النظام | الملف |
958
+ |---|---|
959
+ | ويندوز x64 (ملف واحد) | `kashif-windows-x86_64.exe` — انقر مرّتين لفتح الواجهة |
960
+ | ويندوز x64 (مثبّت) | `kashif-setup.exe` — يثبّت كاشِف ويضيفه إلى PATH (اختياري) مع اختصار في قائمة ابدأ وعلى سطح المكتب، ويُزال من إعدادات ويندوز |
961
+ | لينكس x86-64 | `kashif-linux-x86_64` — Ubuntu 22.04 وDebian 12 وRHEL 9 أو أحدث |
962
+ | macOS (Apple Silicon) | `kashif-macos-arm64` |
963
+ | macOS (Intel) | `kashif-macos-x86_64` |
964
+
965
+ على لينكس:
966
+
967
+ ```bash
968
+ chmod +x kashif-linux-x86_64
969
+ ./kashif-linux-x86_64 # يفتح الواجهة
970
+ ./kashif-linux-x86_64 ./project --fail-on high # سطر الأوامر
971
+ ```
972
+
973
+ على macOS: الملف غير موثَّق (notarized) من Apple، فأزل علامة الحجر مرة واحدة قبل أول تشغيل
974
+ (أو انقر على الملف بالزر الأيمن ← Open):
975
+
976
+ ```bash
977
+ chmod +x kashif-macos-arm64
978
+ xattr -d com.apple.quarantine kashif-macos-arm64
979
+ ./kashif-macos-arm64
980
+ ```
981
+
982
+ كل إصدار يرفق `SHA256SUMS.txt` للتحقق من سلامة الملفات (`sha256sum -c SHA256SUMS.txt --ignore-missing`)،
983
+ وقائمة مكوّنات CycloneDX ‏(`kashif-sbom.cdx.json`)، ومصدر بناء SLSA موقَّعًا يُتحقَّق منه بـ:
984
+
985
+ ```bash
986
+ gh attestation verify kashif-linux-x86_64 --repo abdulrahmanahmedelabed-prog/vulnscan
987
+ ```
988
+
989
+ النسخة تُبنى آليًا عبر GitHub Actions بواسطة PyInstaller من ملف `vulnscan.spec`، وتتضمن الواجهة كاملة.
990
+ لبنائها محليًا: `pip install pyinstaller` ثم `pyinstaller --clean --noconfirm vulnscan.spec` (الناتج في `dist/`).
991
+
992
+ **صفحة الهبوط**: موقع تعريفي في `site/` يُنشر على GitHub Pages ويتضمن المقارنة مع الأدوات العالمية.
993
+
994
+ ### التحديث
995
+
996
+ النسخ الجاهزة تحدّث نفسها: من الواجهة افتح **الإعدادات ← التحديثات** واضغط **حدّث الآن** ثم **أعد التشغيل الآن**،
997
+ وتظهر شارة «تحديث متاح» في الشريط الجانبي عند صدور إصدار أحدث. ومن سطر الأوامر:
998
+
999
+ ```bash
1000
+ kashif update # تحقّق، ثم أكّد، ثم نزّل وتحقّق وثبّت
1001
+ kashif update --check # تحقّق فقط: رمز الخروج 10 عند توفّر تحديث و0 إن كنت على أحدث إصدار
1002
+ kashif update --yes # دون سؤال للتأكيد (للسكربتات)
1003
+ ```
1004
+
1005
+ يُنزَّل التحديث من GitHub فقط عبر HTTPS، ويُطابَق مع `SHA256SUMS.txt` المنشور مع الإصدار، ويُرفض إن لم يكن أحدث،
1006
+ ويُجرَّب (`--version`) قبل أن يحلّ محلّ البرنامج دفعة واحدة؛ وتبقى النسخة السابقة باسم `<الاسم>.old` حتى التشغيل
1007
+ القادم، وأي فشل يعيدها كما كانت. على macOS تُعرض النسخة الأصلية لـ Apple Silicon على نسخة Intel العاملة عبر Rosetta.
1008
+ إن لم يكن مجلد البرنامج قابلًا للكتابة (مثل `/usr/local/bin`) فشغّل `sudo kashif update`. أما تثبيت pip أو الكود
1009
+ المصدري فلا يُعدَّل أبدًا: تعرض الواجهة و`kashif update` الأمر المناسب بدلًا من ذلك. يسأل التحقق `api.github.com`
1010
+ عن أحدث إصدار مرة كل 6 ساعات على الأكثر ولا يرسل شيئًا عن الكود؛ ويمكن إيقافه من خيار
1011
+ **التحقق من التحديثات تلقائيًا** في الإعدادات.
1012
+
1013
+ التثبيت عبر pip قبل الإصدار 1.0.2 يحمل اسم التوزيعة `vulnscan` (وصار اسمها `kashif` منذ 1.0.2)، فأزِله قبل تثبيت
1014
+ الإصدار الجديد وإلا امتلكت التوزيعتان الملفات نفسها (أما `vulnscan` على PyPI فمشروع آخر لا علاقة له بكاشِف):
1015
+
1016
+ ```bash
1017
+ python -m pip uninstall -y vulnscan kashif
1018
+ pip install git+https://github.com/abdulrahmanahmedelabed-prog/vulnscan
1019
+ ```
1020
+
1021
+ ## التشغيل بنقرة واحدة
1022
+
1023
+ بعد تنزيل المشروع وفكّ ضغطه، وتثبيت [Python 3](https://www.python.org/downloads/) (على ويندوز فعّل خيار **Add Python to PATH**):
1024
+
1025
+ | النظام | الملف |
1026
+ |---|---|
1027
+ | ويندوز | انقر مرّتين على **`run.bat`** |
1028
+ | macOS | انقر مرّتين على **`run.command`** |
1029
+ | لينكس | شغّل **`./run.sh`** |
1030
+
1031
+ يفتح المتصفح تلقائيًا على الواجهة. اترك النافذة مفتوحة، وللإيقاف اضغط `Ctrl+C`.
1032
+
1033
+ ## الواجهة الرسومية
1034
+
1035
+ ```bash
1036
+ kashif ui
1037
+ ```
1038
+
1039
+ يفتح المتصفح على `http://127.0.0.1:8765` (الخادم يستمع على هذا الجهاز فقط ولا يُعرَّض للشبكة):
1040
+
1041
+ - **لوحة التحكم**: بطاقات العدّ لكل خطورة، مخطط دائري للتوزيع، اتجاه النتائج عبر الفحوصات الأخيرة،
1042
+ أكثر الثغرات تكرارًا، أكثر الملفات تأثرًا، وآخر الفحوصات.
1043
+ - **فحص جديد**: مسار مجلد/ملف/أرشيف على الجهاز، أو **رفع** (سحب وإفلات) أي برنامج مضغوط
1044
+ (zip / apk / jar / aar / war / whl / ipa / tar.gz) أو أي عدد من الملفات أو مجلد كامل من المتصفح،
1045
+ أو عنوان ويب مع إقرار الصلاحية. تُحذف الملفات المرفوعة بعد الفحص.
1046
+ - **النتائج**: مرتبة من الأعلى خطورة إلى الأقل، مع فلاتر بالخطورة والمصدر وبحث نصي، وبطاقة لكل نتيجة
1047
+ تُفتح لعرض المقتطف وCWE وطريقة الإصلاح، وتنزيل Markdown / JSON / HTML.
1048
+ - **التقارير**: سجل الفحوصات، تنزيل التقارير، و**مقارنة فحصين** لمعرفة ما أُصلح وما استجد.
1049
+ - **القواعد**: استعراض كل القواعد المدمجة مع البحث.
1050
+ - **الإعدادات**: أدنى خطورة، الاستثناءات، القواعد المتجاهَلة، OSV، الأدوات الخارجية، العناوين المصرَّح بها.
1051
+ - عربي/إنجليزي، فاتح/داكن/تلقائي، ومتجاوب مع شاشات الجوال.
1052
+
1053
+ تُحفظ البيانات في `~/.vulnscan` (أو المجلد في `VULNSCAN_HOME`). خيارات: `--port`، `--no-browser`.
1054
+
1055
+ ## الاستخدام من سطر الأوامر
1056
+
1057
+ ```bash
1058
+ # تقرير ملوّن على الشاشة
1059
+ kashif ./my-project
1060
+
1061
+ # تقارير Markdown + JSON + HTML دفعة واحدة
1062
+ kashif ./my-project --all-formats report
1063
+
1064
+ # تقرير HTML فقط إلى ملف
1065
+ kashif app.apk -f html -o report.html
1066
+
1067
+ # في CI: أفشل البناء إذا وُجد شيء عالٍ أو حرج
1068
+ kashif . --fail-on high --exclude "tests/*"
1069
+
1070
+ # دون إنترنت ودون أدوات خارجية
1071
+ kashif . --no-deps --no-external
1072
+
1073
+ # فحص سلبي لموقع تملكه
1074
+ kashif https://my-site.example --authorized
1075
+
1076
+ # عرض القواعد
1077
+ kashif --list-rules .
1078
+
1079
+ # SARIF لـ GitHub Code Scanning وVS Code
1080
+ kashif . -f sarif -o vulnscan.sarif
1081
+
1082
+ # تبنّي الأداة على كود قائم: احفظ الموجود اليوم، ثم اعرض الجديد فقط
1083
+ kashif . --write-baseline .vulnscan-baseline.json
1084
+ kashif . --baseline .vulnscan-baseline.json --fail-on high
1085
+
1086
+ # تقارير GitLab: تبويب الأمان وجودة الكود
1087
+ kashif . -f gitlab-sast -o gl-sast-report.json
1088
+ kashif . -f codeclimate -o gl-code-quality.json
1089
+ ```
1090
+
1091
+ ### الأوامر الفرعية
1092
+
1093
+ يعرض `kashif --help` كل الخيارات والأوامر الفرعية، و`kashif <أمر> --help` خيارات أمر واحد. ويعمل `python3 -m vulnscan`
1094
+ بالطريقة نفسها، ويبقى `vulnscan` اسمًا بديلًا لـ `kashif`.
1095
+
1096
+ | الأمر | ماذا يفعل |
1097
+ |---|---|
1098
+ | `kashif ui` | الواجهة الرسومية المحلية على 127.0.0.1. |
1099
+ | `kashif lsp` | خادم لغة للمحررات: الثغرات تحت الكود أثناء الكتابة مع إصلاحات سريعة. |
1100
+ | `kashif mcp` | خادم MCP يتيح لـ Claude Code وCursor ووكلاء VS Code وWindsurf وZed فحص الكود الذي يكتبونه محليًا ودون إنترنت: `claude mcp add kashif -- kashif mcp`. |
1101
+ | `kashif export report.json -f sonarqube -o sonar.json` | تحويل تقرير JSON إلى DefectDojo وSonarQube وJUnit وCSV وJira وGitHub Issues وASFF وOCSF وGitLab وCode Climate (`kashif export --list-formats`). |
1102
+ | `kashif compliance report.json -f html -o audit.html` | ربط النتائج بأطر OWASP وASVS وCWE Top 25 وPCI DSS وNIST وISO 27001 وHIPAA وGDPR وتقرير قابل للطباعة للمدقق؛ دليل يدعم التقييم وليس شهادة. |
1103
+ | `kashif history .` | كل سرّ أُودِع في تاريخ git ولو حُذف لاحقًا، مع الإيداع الذي أدخله وهل ما زال في HEAD؛ تُخفى قيم الأسرار دائمًا (الاسم البديل `secrets-history`). |
1104
+ | `kashif triage list` | فرز يعيش داخل المستودع (`.kashif/triage.json`): إنذار كاذب، قبول خطر بتاريخ انتهاء، لن يُصلَح، أُصلِح؛ مع صاحب القرار ومبرّره وسجل تدقيق. |
1105
+ | `kashif policy check report.json` | السياسة ككود: بوابة أمان من `kashif.yml` تشرح كل قرار بالعربية أو الإنجليزية (`kashif policy init` يكتب ملفًا أوليًا). |
1106
+ | `kashif surface .` | خريطة سطح الهجوم: نقاط الدخول ومدخلاتها والمصادقة الظاهرة والمصارف التي تصل إليها، وهيكل OpenAPI 3.1؛ تحليل ساكن فقط. |
1107
+ | `kashif rules new my-pack` | اكتب قواعدك واختبرها: `new` و`test` و`lint` و`pack` و`verify` و`install` و`list` و`docs`؛ وافحص بالحزم المثبّتة عبر `--pack NAME` أو `--packs`. |
1108
+ | `kashif update` | تثبيت أحدث إصدار رسمي بعد التحقق منه (`--check` للتحقق فقط). |
1109
+ | `kashif update-data --web` | تثبيت بيانات فاحص المواقع من حزمة آخر إصدار رسمي بعد التحقق من بصمتها SHA-256 (`--check` للتحقق فقط)؛ لا يُرسل شيء عن المواقع التي تفحصها، ودونه تُستخدم البيانات المضمّنة. |
1110
+
1111
+ ### التكامل مع GitHub Code Scanning (SARIF)
1112
+
1113
+ ```yaml
1114
+ permissions:
1115
+ security-events: write # يلزم لرفع SARIF
1116
+ # ...
1117
+ - run: pip install git+https://github.com/abdulrahmanahmedelabed-prog/vulnscan && vulnscan . --no-deps -f sarif -o vulnscan.sarif
1118
+ - uses: github/codeql-action/upload-sarif@v3
1119
+ with:
1120
+ sarif_file: vulnscan.sarif
1121
+ ```
1122
+
1123
+ تظهر النتائج في تبويب Security ومباشرة على أسطر طلبات الدمج، مع درجة خطورة رقمية وCWE ومسار تدفق البيانات
1124
+ (من المصدر إلى نقطة الخطر). كل نتيجة تحمل بصمة ثابتة لا تتغير بتحريك السطر أو إعادة تنسيقه، فلا تتكرر الإنذارات.
1125
+
1126
+ ### خط الأساس (Baseline)
1127
+
1128
+ على كود قائم فيه مئات النتائج القديمة، احفظ بصماتها مرة واحدة بـ `--write-baseline` واحفظ الملف في المستودع
1129
+ (لا يحوي كودًا، بصمات فقط). بعدها `--baseline` يكتم المعروف ويعرض **الجديد فقط**، و`--fail-on` يُفشل البناء
1130
+ على الجديد وحده. البصمة = القاعدة + الملف + المقتطف بلا مسافات، فتصمد أمام إزاحة الأسطر وإعادة التنسيق.
1131
+
1132
+ ### كشف الأسرار
1133
+
1134
+ أنماط مزوّدين محددة (AWS وGitHub وSlack وStripe وGoogle وSendGrid وTwilio وMailgun وnpm وPyPI وDigitalOcean
1135
+ وShopify وSquare وFacebook وTelegram، وروابط Webhook، ومفاتيح حساب خدمة GCP، ومفاتيح Azure Storage)،
1136
+ إضافة إلى **كشف بالعشوائية (إنتروبيا شانون)** على نهج gitleaks وtrufflehog يلتقط مفاتيح مزوّدين لا نمط لهم،
1137
+ مع تجاهل التجزئات السداسية وقيم الأمثلة وبيانات base64 للصور وتجزئات integrity.
1138
+
1139
+ ### الخيارات
1140
+
1141
+ | الخيار | الوصف |
1142
+ |---|---|
1143
+ | `-f console\|markdown\|json\|html\|sarif` | صيغة التقرير (sarif لـ GitHub Code Scanning وVS Code)؛ ويقبل أيضًا صيغ التصدير مثل `gitlab-sast` و`codeclimate` و`defectdojo` و`sonarqube` و`junit` و`csv` |
1144
+ | `--export FORMAT=FILE` | كتابة الفحص نفسه بصيغة تصدير إضافية (يُكرَّر) |
1145
+ | `--triage[=FILE]` / `--triage-update` / `--triage-show STATUSES` | تطبيق قرارات الفرز / حفظ ما تغيّر (للفرع الرئيسي فقط) / الحالات المعروضة |
1146
+ | `--sla SPEC` / `--fail-on-sla` | مهلة الإصلاح لكل خطورة / رمز خروج 1 عند تجاوزها |
1147
+ | `--policy[=FILE]` / `--no-policy` / `--policy-reports-dir DIR` | بوابة السياسة (يُطبَّق `kashif.yml` الموجود في المجلد تلقائيًا) / تعطيلها / مجلد تقاريرها |
1148
+ | `--compliance FRAMEWORKS` / `--audit-report FILE` | ملخص الامتثال بعد التقرير / تقرير المدقق HTML |
1149
+ | `--risk-score` | درجة خطر كاشِف للمشروع (0-10؛ ليست درجة CVSS) |
1150
+ | `--pack NAME` / `--packs` | استخدام حزمة قواعد مثبّتة / كل الحزم |
1151
+ | `--baseline FILE` / `--write-baseline FILE` | اعرض الجديد فقط مقارنة بخط أساس / احفظ خط الأساس |
1152
+ | `-o FILE` | كتابة التقرير إلى ملف |
1153
+ | `--all-formats PREFIX` | كتابة `PREFIX.md` و `PREFIX.json` و `PREFIX.html` و `PREFIX.sarif` |
1154
+ | `--min-severity LEVEL` | عرض هذه الخطورة فما فوق |
1155
+ | `--fail-on LEVEL` | رمز خروج 1 عند وجود نتيجة بهذه الخطورة أو أعلى |
1156
+ | `--exclude GLOB` | استثناء مسارات (يُكرَّر) |
1157
+ | `--ignore-rule ID` | تجاهل قاعدة (يُكرَّر) |
1158
+ | `--no-deps` / `--no-external` | تعطيل OSV / الأدوات الخارجية |
1159
+ | `--no-jadx` / `--jadx-timeout SEC` / `--jadx-include-libs` | التحكم في فك التجميع عبر jadx |
1160
+ | `--authorized` | إقرار بالصلاحية (إلزامي لعناوين الويب) |
1161
+ | `--deep` | فحص ويب أعمق (تحليل الصفحة ومسارات مكشوفة شائعة) |
1162
+ | `--crawl` / `--max-pages` / `--max-depth` | زحف على صفحات الموقع وفحصها (لتطبيقات مثل Moodle وAPEX) |
1163
+
1164
+ ### كتم إنذار مقصود
1165
+
1166
+ أضف في نهاية السطر `# nosec` أو `// vulnscan: ignore`. ولكتم ملف كامل ضع `vulnscan: ignore-file`
1167
+ في أول سطوره.
1168
+
1169
+ ## شكل التقرير
1170
+
1171
+ ```
1172
+ Kashif — ./my-project (156 ملفًا مفحوصًا، 37 نتيجة)
1173
+
1174
+ الملخص (من الأعلى خطورة إلى الأقل):
1175
+ حرج CRITICAL 0
1176
+ عالٍ HIGH 3
1177
+ متوسط MEDIUM 8
1178
+ منخفض LOW 26
1179
+ معلوماتي INFO 0
1180
+
1181
+ ━━ عالٍ / HIGH (3) ━━
1182
+ 🟧 MOB001 [CWE-319] السماح بحركة مرور غير مشفّرة — Cleartext traffic allowed
1183
+ 📄 app/android/app/src/main/AndroidManifest.xml:6
1184
+ ▸ android:usesCleartextTraffic="true"
1185
+ 💡 عطّل cleartext واستخدم HTTPS فقط …
1186
+ ```
1187
+
1188
+ تقرير Markdown يبدأ بملخص تنفيذي وجدول أعداد، ثم «أهم ما يجب إصلاحه أولًا»، ثم كل النتائج مجمّعة حسب الخطورة
1189
+ مع المعرّف و CWE والموضع والمقتطف وطريقة الإصلاح. تقرير JSON يحمل الحقول نفسها لدمجه في أدوات أخرى.
1190
+
1191
+ ## الدقة: OWASP Benchmark
1192
+
1193
+ نقيس كاشِف على مجموعتي OWASP Benchmark الرسميتين بطريقة OWASP في الحساب (متوسط معدّل الإيجابيات الصحيحة ناقص معدّل
1194
+ الإيجابيات الكاذبة لكل فئة)، بأداة التقييم الخاصة بالمشروع (`bench/score_owasp.py`) لا بأداة Scorecard الرسمية:
1195
+ **Python ‏74.0%** (1,230 حالة) و**Java ‏98.3%** (2,740 حالة؛ كانت 76.3% في 0.9). تُفحص كل مجموعة كاملة كتطبيق واحد
1196
+ بالملف الافتراضي، ولا يحوي المحرّك أي اسم أو مسار أو نتيجة من ملفات الاختبار.
1197
+
1198
+ قفزة Java سببها إصلاحان عامّان في حلّ الاستدعاءات (استدعاء دالة بلا كائن يُحلّ إلى دالة الصنف نفسه، ودوال المكتبات
1199
+ الشائعة مثل `toString` لا تُربط بدالة في المشروع تحمل الاسم نفسه). دقّقها مراجع مستقل: نسخة أُعيدت تسمية كل ما فيها
1200
+ أعطت 98.3% نفسها، ونجحت 516 من 516 حالة تحويل. لكن Benchmark مجموعة اصطناعية، فلا تُقرأ النتيجة دقةً على الكود
1201
+ الحقيقي، وما زالت 38 حالة XSS في Java إنذارًا كاذبًا (FPR ‏18.2%). الجدول الكامل لكل فئة في القسم الإنجليزي أعلاه وفي
1202
+ صفحة الهبوط، وتعيد إنتاجه بأمر واحد:
1203
+
1204
+ ```bash
1205
+ git clone --depth 1 https://github.com/OWASP-Benchmark/BenchmarkJava && python bench/score_owasp.py BenchmarkJava
1206
+ ```
1207
+
1208
+ ## مقارنة مع الأدوات العالمية
1209
+
1210
+ | | **كاشِف** | Semgrep | SonarQube | Snyk Code | GitHub CodeQL | Bandit | Trivy |
1211
+ |---|---|---|---|---|---|---|---|
1212
+ | نوع التحليل | أنماط + تدفق بيانات مدرك للأنواع عبر الملفات مع points-to حسّاس للسياق (k=2) وحسّاس للتدفق (12 لغة) + نماذج كبيانات + VQL بأصناف ومسندات ذاتية وتجميعات | أنماط دلالية + تتبع بيانات (Pro) | تحليل دلالي عميق | تحليل دلالي + تعلّم آلي | تحليل تدفق بيانات بلغة استعلام | AST لـ Python | إعدادات + اعتماديات + حاويات |
1213
+ | اللغات | 15+ أنماط · تدفق بيانات لـ 12 لغة | 30+ | 30+ | 15+ | 10+ | Python فقط | — (لا كود) |
1214
+ | كشف الأسرار | ✅ | محدود | ✅ (نسخ مدفوعة) | ✅ | ✅ | ❌ | ✅ |
1215
+ | ثغرات الاعتماديات (CVE) | ✅ عبر OSV.dev | ✅ (Supply Chain) | محدود | ✅ قوي | ✅ Dependabot | ❌ | ✅ قوي |
1216
+ | فحص أرشيف / APK / JAR | ✅ + فك تجميع عبر jadx | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ (صور وملفات) |
1217
+ | فحص ويب سلبي (ترويسات/CSP/TLS/شهادة/مسارات مكشوفة) | ✅ | ❌ | ❌ | محدود (SaaS) | ❌ | ❌ | ❌ |
1218
+ | واجهة رسومية محلية | ✅ بلا خادم خارجي | ❌ (SaaS) | ✅ (تحتاج خادم وقاعدة بيانات) | SaaS | على GitHub | ❌ | ❌ |
1219
+ | التقرير مرتّب حسب الخطورة | ✅ أساسًا | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1220
+ | مخرجات SARIF وخط أساس (الجديد فقط) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ (SARIF) | ✅ |
1221
+ | مقارنة فحصين (ما أُصلح/ما استجد) | ✅ | في SaaS | ✅ | ✅ | ✅ | ❌ | ❌ |
1222
+ | يعمل دون إنترنت | ✅ (عدا OSV) | ✅ محليًا | ✅ | ❌ | ✅ CLI | ✅ | ✅ (بعد تنزيل DB) |
1223
+ | الاعتماديات | **صفر** (Python فقط) | ثنائي + قواعد | Java + DB | حساب Snyk | CodeQL CLI | pip | ثنائي Go |
1224
+ | العربية | ✅ عناوين وإصلاحات بالعربية | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
1225
+ | السعر | مجاني (MIT) | مجاني/مدفوع | Community/مدفوع | مجاني محدود/مدفوع | مجاني للمفتوح | مجاني | مجاني |
1226
+
1227
+ **أين يتفوق كاشِف؟** خفيف جدًا وبلا اعتماديات، يجمع تحليل تدفق البيانات في 12 لغة مع ملفات الإعداد والحاويات وCI
1228
+ والموبايل وOracle APEX في أداة واحدة، يقبل الأرشيفات وAPK مباشرة، واجهته وتقاريره بالعربية، ويقترح إصلاحات مُتحقَّقًا
1229
+ منها، ويدمج تلقائيًا نتائج Semgrep وBandit وgitleaks وnpm audit إن وُجدت فيصبح لوحة واحدة فوقها.
1230
+
1231
+ **أين تتفوق الأدوات العالمية؟** CodeQL وSemgrep Pro وSonarQube وSnyk لديها آلاف القواعد ونماذج مكتبات أوسع بكثير،
1232
+ وسنوات من الضبط على قواعد كود ضخمة. إن كنت تستخدمها فأبقِها، وشغّل كاشِف بجانبها حيث يسدّ فجوة (العمل المحلي الكامل،
1233
+ وAPEX وPL/SQL، والأرشيفات، والعربية).
1234
+
1235
+ ## الاستخدام في بيئات الإنتاج
1236
+
1237
+ بدءًا من 1.0 يلتزم كاشِف بالترقيم الدلالي وبعقد ثبات مكتوب: خيارات سطر الأوامر ورموز الخروج، وصيغ تقارير JSON وSARIF
1238
+ وGitLab وCode Climate، وبصمات النتائج وملفات خط الأساس، ومعرّفات القواعد، وتعليقات الكتم، لا تنكسر داخل 1.x. وتُنشر صورة
1239
+ حاوية (`linux/amd64` و`linux/arm64`، بمستخدم غير جذري):
1240
+
1241
+ ```bash
1242
+ docker run --rm -v "$PWD:/src" ghcr.io/abdulrahmanahmedelabed-prog/kashif:1 .
1243
+ ```
1244
+
1245
+ عقد الثبات وسياسة الدعم وطرق النشر (CI، والشبكات المعزولة، ولوحة مركزية خلف وسيط عكسي يوثّق المستخدمين) في
1246
+ [docs/production.md](docs/production.md).
1247
+
1248
+ ## التطوير
1249
+
1250
+ ```bash
1251
+ pip install -e .[dev]
1252
+ python -m pytest -q
1253
+ ```
1254
+
1255
+ البنية: `scanner.py` (المشي على الملفات والأرشيفات) · `rules.py` (القواعد) · `deps.py` (OSV) · `web.py` (الفحص السلبي)
1256
+ · `external.py` (الأدوات الخارجية) · `report.py` (التقارير) · `server.py` + `ui/` (الواجهة) · `store.py` (الإعدادات والسجل) · `cli.py`.
1257
+
1258
+ ## حدود الأداة
1259
+
1260
+ - الفحص الثابت بالقواعد يكشف الأنماط الشائعة ولا يغني عن مراجعة بشرية أو اختبار اختراق.
1261
+ - قد تظهر إنذارات كاذبة؛ استخدم `--ignore-rule` أو كتم السطر بعد التحقق.
1262
+ - غير منمذج بعد: القوالب غير Jinja (مثل EJS وERB)، والقيم التي تصل إلى ملف PHP عبر `include`، والقيم التي تمرّ عبر
1263
+ ملفات أو قواعد بيانات خارج الكود المفحوص. والمشاريع الكبيرة تحتاج ذاكرة: Django (نحو 7,000 ملف) تصل إلى نحو 3.5 GB.
1264
+ - النماذج أقل من الأدوات التجارية الكبرى (نحو 6,350 واجهة مكتبة و153 قاعدة نمطية)، والضبط على الكود الحقيقي أقل (ضُبط
1265
+ الإصدار 1.0 على 38 مشروعًا مفتوح المصدر).
1266
+ - بدون jadx تُفحص محتويات APK/JAR النصية فقط؛ ومع jadx يُفحص الكود المفكوك وهو كود مُعاد توليده قد يختلف عن المصدر الأصلي.
1267
+ - فحص الويب سلبي بالكامل (طلبات GET عادية فقط، ضمن حدّ معلَن لكل نمط فحص: `minimal` طلب واحد بتوجيهاته كما في 1.0)
1268
+ ولا يُجري أي اختبار نشط: يرى الصفحات العامة فقط، ولا يختبر الحقن ولا XSS ولا المصادقة ولا التحكم في الوصول ولا منطق
1269
+ العمل، ولا يتحقق من إلغاء الشهادة؛ ودرجته تقيس سلامة الإعدادات لا خلوّ الموقع من الثغرات.
1270
+
1271
+ ## حول كاشِف
1272
+
1273
+ كاشِف من تطوير دائرة البرمجة في الجامعة الإسلامية بغزة. للتواصل: [its@iugaza.edu.ps](mailto:its@iugaza.edu.ps) و[aelabed@iugaza.edu.ps](mailto:aelabed@iugaza.edu.ps)
1274
+
1275
+ ## الرخصة
1276
+
1277
+ MIT