1 2 3<!DOCTYPE html> 4<html class="writer-html5" lang="en" data-content_root="../"> 5<head> 6 <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> 7 8 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 9 <title>KXDB Database — kernelXDK 0.0.1 documentation</title> 10 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" /> 11 <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" /> 12 <link rel="stylesheet" type="text/css" href="../_static/collapsible-lists/css/tree_view.css?v=a885cde7" /> 13 14 15
15<script src="../_static/jquery.js?v=5d32c60e"></script>
15 16
16<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
16 17
17<script src="../_static/documentation_options.js?v=d45e8c67"></script>
17 18
18<script src="../_static/doctools.js?v=9bcbadda"></script>
18 19
19<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
19 20
20<script src="../_static/collapsible-lists/js/CollapsibleLists.compressed.js?v=73120307"></script>
20 21
21<script src="../_static/collapsible-lists/js/apply-collapsible-lists.js?v=660e4f45"></script>
21 22
22<script src="../_static/js/theme.js"></script>
22 23 <link rel="index" title="Index" href="../genindex.html" /> 24 <link rel="search" title="Search" href="../search.html" /> 25 <link rel="next" title="What is libxdk?" href="../libxdk/README.html" /> 26 <link rel="prev" title="Introduction" href="introduction.html" /> 27</head> 28 29<body class="wy-body-for-nav"> 30 <div class="wy-grid-for-nav"> 31 <nav data-toggle="wy-nav-shift" class="wy-nav-side"> 32 <div class="wy-side-scroll"> 33 <div class="wy-side-nav-search" > 34 35 36 37 <a href="../index.html" class="icon icon-home"> 38 kernelXDK 39 </a> 40<div role="search"> 41 <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> 42 <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> 43 <input type="hidden" name="check_keywords" value="yes" /> 44 <input type="hidden" name="area" value="default" /> 45 </form> 46</div> 47 </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> 48 <p class="caption" role="heading"><span class="caption-text">About</span></p> 49<ul class="current"> 50<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> 51<li class="toctree-l1"><a class="reference internal" href="introduction.html#what-is-kernelxdk">What is kernelXDK?</a></li> 52<li class="toctree-l1 current"><a class="current reference internal" href="#">KXDB Database</a><ul> 53<li class="toctree-l2"><a class="reference internal" href="#database-concept">Database concept</a></li> 54<li class="toctree-l2"><a class="reference internal" href="#kxdb-file-format">KXDB file format</a><ul> 55<li class="toctree-l3"><a class="reference internal" href="#design-goals">Design goals</a></li> 56</ul> 57</li> 58<li class="toctree-l2"><a class="reference internal" href="#contents">Contents</a><ul> 59<li class="toctree-l3"><a class="reference internal" href="#configuration-file">Configuration file</a></li> 60</ul> 61</li> 62<li class="toctree-l2"><a class="reference internal" href="#kernelctf-kxdb-distribution">kernelCTF KXDB distribution</a></li> 63</ul> 64</li> 65</ul> 66<p class="caption" role="heading"><span class="caption-text">libxdk</span></p> 67<ul> 68<li class="toctree-l1"><a class="reference internal" href="../libxdk/README.html">What is libxdk?</a></li> 69<li class="toctree-l1"><a class="reference internal" href="../libxdk/README.html#installation">Installation</a></li> 70<li class="toctree-l1"><a class="reference internal" href="../libxdk/how_to_get_started.html">How to get started</a></li> 71<li class="toctree-l1"><a class="reference internal" href="../libxdk/sample_exploit.html">How to port an existing exploit</a></li> 72<li class="toctree-l1"><a class="reference internal" href="../libxdk/api.html">API Reference</a></li> 73</ul> 74<p class="caption" role="heading"><span class="caption-text">Command Line Tools</span></p> 75<ul> 76<li class="toctree-l1"><a class="reference internal" href="../commandline_tools/image_db.html">Kernel Image DB</a></li> 77<li class="toctree-l1"><a class="reference internal" href="../commandline_tools/image_runner.html">Kernel Image Runner</a></li> 78<li class="toctree-l1"><a class="reference internal" href="../commandline_tools/kxdb_tool.html">KXDB Tool</a></li> 79<li class="toctree-l1"><a class="reference internal" href="../commandline_tools/rop_generator.html">Kernel ROP Generator</a></li> 80</ul> 81 82 </div> 83 </div> 84 </nav> 85 86 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > 87 <i data-toggle="wy-nav-top" class="fa fa-bars"></i> 88 <a href="../index.html">kernelXDK</a> 89 </nav> 90 91 <div class="wy-nav-content"> 92 <div class="rst-content"> 93 <div role="navigation" aria-label="Page navigation"> 94 <ul class="wy-breadcrumbs"> 95 <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li> 96 <li class="breadcrumb-item active">KXDB Database</li> 97 <li class="wy-breadcrumbs-aside"> 98 <a href="../_sources/about/kxdb_database.md.txt" rel="nofollow"> View page source</a> 99 </li> 100 </ul> 101 <hr/> 102</div> 103 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> 104 <div itemprop="articleBody"> 105 106 <section id="kxdb-database"> 107<h1>KXDB Database<a class="headerlink" href="#kxdb-database" title="Link to this heading">ï</a></h1> 108<section id="database-concept"> 109<h2>Database concept<a class="headerlink" href="#database-concept" title="Link to this heading">ï</a></h2> 110<p>The traditional approach to kernel exploits involves embedding target-specific information (such as symbol, function, ROP gadget, and stack pivot addresses, along with structure and field sizes/offsets) directly into the exploitâs source code using <code class="docutils literal notranslate"><span class="pre">#define</span></code>s. While these values can be replaced when porting, this method requires the exploit to be manually modified and recompiled for every new target.</p> 111<p>kernelXDK decouples this target-specific information from the exploit by storing it in a database. This database contains data for multiple targets, allowing the exploit to dynamically detect the running target and use the correct offsets at runtime (rather than at compile time).</p> 112</section> 113<section id="kxdb-file-format"> 114<h2>KXDB file format<a class="headerlink" href="#kxdb-file-format" title="Link to this heading">ï</a></h2> 115<p>To store this information, we introduced a new binary file format called the Kernel eXploit DataBase (KXDB), with the file extension <code class="docutils literal notranslate"><span class="pre">.kxdb</span></code>.</p> 116<p>The precise structure of this file format is detailed in the <a class="reference external" href="https://github.com/google/kernel-research/blob/main/docs/kxdb_file_format.txt">kxdb_file_format.txt</a> file.</p> 117<p>This database offers flexible integration: it can be included directly into the exploit binary as a binary blob, read from a separate file, or a combination of both approaches can be used. For instance, an exploit can be built with an up-to-date database at compilation time, yet allow it to be replaced with a newer version by placing the <code class="docutils literal notranslate"><span class="pre">.kxdb</span></code> file next to the exploit binary.</p> 118<section id="design-goals"> 119<h3>Design goals<a class="headerlink" href="#design-goals" title="Link to this heading">ï</a></h3> 120<ul class="simple"> 121<li><p>Minimize size:</p> 122<ul> 123<li><p><strong>Binary format</strong> instead of text.</p></li> 124<li><p><strong>Avoid unnecessary repetiton</strong>: e.g. if a structure layout is identical across two targets, itâs stored only once.</p></li> 125<li><p><strong>Variable-size integers</strong> to eliminate unnecessary zero bytes.</p></li> 126</ul> 127</li> 128<li><p>Backwards compatibility and extendibility:</p> 129<ul> 130<li><p><strong>Minor versions</strong> can introduce new fields without breaking backwards compatibility, allowing older exploits to utilize new database files.</p></li> 131<li><p><strong>Major versions</strong> can introduce breaking changes.</p></li> 132</ul> 133</li> 134<li><p>Searchable and seekable*:</p> 135<ul> 136<li><p><strong>Seekable structures</strong> allow skipping unnecessary information (e.g. data for non-current targets).</p></li> 137<li><p>Internal structures are organized alphabetically to allow <strong>binary searching</strong>.</p></li> 138</ul> 139</li> 140<li><p>Optimized for parsing:</p> 141<ul> 142<li><p>Strings are stored as length-prefixed, zero-terminated strings so standard C APIs (e.g. <code class="docutils literal notranslate"><span class="pre">strcmp</span></code>) can be used directly.</p></li> 143</ul> 144</li> 145</ul> 146<p>*<em>Note: While the format is designed to be searchable and seekable, the current <code class="docutils literal notranslate"><span class="pre">libxdk</span></code> implementation reads the entire metadata section and performs linear searches for targets, and reads all target-specific information. This will be optimized in a future release.</em></p> 147</section> 148</section> 149<section id="contents"> 150<h2>Contents<a class="headerlink" href="#contents" title="Link to this heading">ï</a></h2> 151<ul class="simple"> 152<li><p>symbol addresses - e.g. <code class="docutils literal notranslate"><span class="pre">prepare_kernel_cred</span></code>, <code class="docutils literal notranslate"><span class="pre">init_nsproxy</span></code>, <code class="docutils literal notranslate"><span class="pre">anon_pipe_buf_ops</span></code></p></li> 153<li><p>ROP actions (configurable ROP chains which execute predefined functionality):</p> 154<ul> 155<li><p><code class="docutils literal notranslate"><span class="pre">msleep(ARG_time_msec)</span></code></p></li> 156<li><p><code class="docutils literal notranslate"><span class="pre">commit_creds(prepare_kernel_cred(&init_task))</span></code></p></li> 157<li><p><code class="docutils literal notranslate"><span class="pre">switch_task_namespaces(find_task_by_vpid(ARG_vpid=1),</span> <span class="pre">init_nsproxy)</span></code></p></li> 158<li><p><code class="docutils literal notranslate"><span class="pre">write_what_where_64(ARG_address,</span> <span class="pre">ARG_new_value)</span></code></p></li> 159<li><p><code class="docutils literal notranslate"><span class="pre">fork()</span></code></p></li> 160<li><p><code class="docutils literal notranslate"><span class="pre">telefork(ARG_sleep_msec=0xffffffff)</span></code></p></li> 161<li><p><code class="docutils literal notranslate"><span class="pre">ret_via_kpti_retpoline(ARG_user_rip,</span> <span class="pre">ARG_user_cs,</span> <span class="pre">ARG_user_rflags,</span> <span class="pre">ARG_user_sp,</span> <span class="pre">ARG_user_ss)</span></code></p></li> 162</ul> 163</li> 164<li><p>structure names, sizes</p></li> 165<li><p>field names, offsets and sizes</p></li> 166<li><p>stack pivots:</p> 167<ul> 168<li><p>one gadgets (e.g. <code class="docutils literal notranslate"><span class="pre">mov</span> <span class="pre">rsp,</span> <span class="pre">rdi</span></code>)</p></li> 169<li><p>push indirects (e.g. <code class="docutils literal notranslate"><span class="pre">push</span> <span class="pre">rsi</span> <span class="pre">;</span>  <span class="pre">jmp</span> <span class="pre">
169qword</span> <span class="pre">[rsi+0x30]</span></code>)</p></li> 170<li><p>pop rsps (e.g. <code class="docutils literal notranslate"><span class="pre">pop</span> <span class="pre">rsp;</span> <span class="pre">ret</span></code>)</p></li> 171<li><p>stack shifts</p></li> 172</ul> 173</li> 174<li><p>target information</p> 175<ul> 176<li><p>distribution (e.g. <code class="docutils literal notranslate"><span class="pre">kernelctf</span></code> or <code class="docutils literal notranslate"><span class="pre">ubuntu</span></code>)</p></li> 177<li><p>release name (e.g. <code class="docutils literal notranslate"><span class="pre">lts-6.12.40</span></code>)</p></li> 178<li><p>version (contents of <code class="docutils literal notranslate"><span class="pre">/proc/version</span></code>)</p></li> 179</ul> 180</li> 181</ul> 182<section id="configuration-file"> 183<h3>Configuration file<a class="headerlink" href="#configuration-file" title="Link to this heading">ï</a></h3> 184<p>You can configure the database contents using the file located at <a class="reference external" href="https://github.com/google/kernel-research/blob/main/kxdb_tool/config.py">kxdb_tool/config.py</a>. Once configured, a new database can be generated by running the <a class="reference external" href="https://github.com/google/kernel-research/actions/workflows/db-upgrade-to-new-config.yml">DB: upgrade to new config</a> GitHub Action workflow (this requires assistance from a project maintainer).</p> 185</section> 186</section> 187<section id="kernelctf-kxdb-distribution"> 188<h2>kernelCTF KXDB distribution<a class="headerlink" href="#kernelctf-kxdb-distribution" title="Link to this heading">ï</a></h2> 189<p>The latest database version, which includes all kernelCTF targets, is available at <a class="reference external" href="https://storage.googleapis.com/kernelxdk/db/kernelctf.kxdb">https://storage.googleapis.com/kernelxdk/db/kernelctf.kxdb</a>.</p> 190<p>This file is updated daily via the <a class="reference external" href="https://github.com/google/kernel-research/actions/workflows/db-add-missing-releases.yml">DB: add missing releases</a> Github Action workflow.</p> 191</section> 192</section> 193 194 195 </div> 196 </div> 197 <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> 198 <a href="introduction.html" class="btn btn-neutral float-left" title="Introduction" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> 199 <a href="../libxdk/README.html" class="btn btn-neutral float-right" title="What is libxdk?" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> 200 </div> 201 202 <hr/> 203 204 <div role="contentinfo"> 205 <p>© Copyright 2025, Google.</p> 206 </div> 207 208 Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a 209 <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> 210 provided by <a href="https://readthedocs.org">Read the Docs</a>. 211 212 213</footer> 214 </div> 215 </div> 216 </section> 217 </div> 218
218<script> 219 jQuery(function () { 220 SphinxRtdTheme.Navigation.enable(true); 221 }); 222 </script>
222 223 224</body> 225</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.