Install file(1) in the Debian CI job so shlibdeps can run

cpack's CPACK_DEBIAN_PACKAGE_SHLIBDEPS runs dpkg-shlibdeps, which needs
the file utility to detect ELF binaries and derive the runtime libc
dependency. The slim CI image does not ship it, so packaging failed at
the cpack step. Add file to the job toolchain.

.gitea/workflows/release.yml

@@ -70,3 +70,58 @@ jobs:
           curl -fsSL -X POST -H "$auth" \
             -F "attachment=@dist/${asset};type=application/zip" \
             "${api}/releases/${rid}/assets?name=${asset}"
+
+  deb:
+    runs-on: ubuntu-latest
+    container:
+      image: node:20-bookworm-slim
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install toolchain
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends \
+            cmake make gcc libc6-dev dpkg-dev file \
+            gcc-mingw-w64-x86-64 ca-certificates curl
+
+      - name: Configure
+        env:
+          TAG: ${{ github.ref_name }}
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DVMIE_VERSION=${TAG#v}
+
+      - name: Build shared library
+        run: cmake --build build -j --target vmie_shared
+
+      - name: Package
+        run: |
+          set -euo pipefail
+          (cd build && cpack -G DEB)
+          ls -l build/*.deb
+
+      - name: Publish to Debian registry
+        env:
+          TOKEN: ${{ secrets.PUBLISH_TOKEN }}   # requires scope: package:write
+          SERVER: ${{ github.server_url }}
+          OWNER: ${{ github.repository_owner }}
+          DISTRIBUTION: stable
+          COMPONENT: main
+        run: |
+          set -euo pipefail
+          url="${SERVER}/api/packages/${OWNER}/debian/pool/${DISTRIBUTION}/${COMPONENT}/upload"
+          auth="Authorization: token ${TOKEN}"
+          for deb in build/*.deb; do
+            # 201 Created = uploaded; 409 Conflict = this version already present (re-run).
+            # Both are success; anything else fails. Do not use curl -f (it would fail 409).
+            code=$(curl -s -o /dev/null -w '%{http_code}' \
+              -X PUT -H "$auth" -T "$deb" "$url")
+            echo "$deb -> HTTP $code"
+            if [ "$code" != 201 ] && [ "$code" != 409 ]; then
+              echo "upload failed: $deb (HTTP $code)" >&2
+              exit 1
+            fi
+          done

CMakeLists.txt

@@ -1,15 +1,19 @@
 cmake_minimum_required(VERSION 3.18)   # find_program(... REQUIRED)
-project(vmi-engine C)
+
+set(VMIE_VERSION "0.1.5" CACHE STRING "Library version (MAJOR.MINOR.PATCH); CI passes the tag")
+project(vmi-engine VERSION ${VMIE_VERSION} LANGUAGES C)
 
 set(CMAKE_C_STANDARD 17)               # generation B uses no C23 feature
 set(CMAKE_C_STANDARD_REQUIRED ON)
 set(CMAKE_C_EXTENSIONS ON)             # deliberate: strnlen (POSIX) + void* arithmetic (GNU)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON) # -fPIC on all objects: static lib stays linkable into a shared object
 
+include(GNUInstallDirs)
+
 option(VMIE_LTO "Enable LTO" OFF)      # build-only; shipped default is -O2, no LTO
 
-# ---- host: VMI core as a static library ---------------------------------
+# ---- host: VMI core objects (single owner of the source list) -----------
-add_library(vmie STATIC
+add_library(vmie_obj OBJECT
         src/core/gpa.c
         src/engine/gva.c
         src/engine/sigphys.c
@@ -27,15 +31,32 @@ add_library(vmie STATIC
         src/handlers/x86dec.c
         src/handlers/pmap.c
         src/handlers/snapdiff.c)
-target_include_directories(vmie
+target_include_directories(vmie_obj
         PUBLIC  ${CMAKE_CURRENT_SOURCE_DIR}/include              # public API: include/*.h
         PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/core/include     # private: core.h
                 ${CMAKE_CURRENT_SOURCE_DIR}/src/engine/include   # private: engine-arch.h, pe.h
                 ${CMAKE_CURRENT_SOURCE_DIR}/src/engine/win32)    # private: engine-win32.h, contract.h
-target_compile_options(vmie PRIVATE -O2 -Wall -Wextra)
+target_compile_options(vmie_obj PRIVATE -O2 -Wall -Wextra)
 if(VMIE_LTO)
-    target_compile_options(vmie PRIVATE -flto)
+    target_compile_options(vmie_obj PRIVATE -flto)
-    target_link_options(vmie PRIVATE -flto)
+    target_link_options(vmie_obj PRIVATE -flto)
+endif()
+
+# ---- host: static library (in-tree consumers: CLIs + test) --------------
+# $<TARGET_OBJECTS:> carries object files only, not usage requirements:
+# re-declare the PUBLIC include scope so vmie_cli/vmie_scan still see include/.
+add_library(vmie STATIC $<TARGET_OBJECTS:vmie_obj>)
+target_include_directories(vmie PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
+
+# ---- host: shared library (external delivery: libvmie.so.*) -------------
+add_library(vmie_shared SHARED $<TARGET_OBJECTS:vmie_obj>)
+target_include_directories(vmie_shared PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
+set_target_properties(vmie_shared PROPERTIES
+        OUTPUT_NAME vmie
+        SOVERSION   ${PROJECT_VERSION_MAJOR}
+        VERSION     ${PROJECT_VERSION})
+if(VMIE_LTO)
+    target_link_options(vmie_shared PRIVATE -flto)
 endif()
 
 # ---- host: CLI demonstrator over the library ----------------------------
@@ -61,3 +82,44 @@ add_custom_command(
         COMMENT "Cross-compiling vmie-startup.exe (mingw-w64, x86-64)"
         VERBATIM)
 add_custom_target(vmie-startup ALL DEPENDS ${VMIE_STARTUP})
+
+# ---- install: shared library + public headers ---------------------------
+# Versioned file + SONAME symlink -> runtime; unversioned linker symlink -> dev.
+install(TARGETS vmie_shared
+        LIBRARY
+          DESTINATION ${CMAKE_INSTALL_LIBDIR}
+          COMPONENT runtime
+          NAMELINK_COMPONENT dev)
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/vmie
+        COMPONENT dev
+        FILES_MATCHING PATTERN "*.h")
+
+# ---- package: two Debian packages (runtime + dev) -----------------------
+set(CPACK_GENERATOR "DEB")
+set(CPACK_DEB_COMPONENT_INSTALL ON)
+set(CPACK_COMPONENTS_ALL runtime dev)
+set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
+
+# component -> Debian package name (Debian shared-library convention)
+set(CPACK_DEBIAN_RUNTIME_PACKAGE_NAME "libvmie${PROJECT_VERSION_MAJOR}")
+set(CPACK_DEBIAN_DEV_PACKAGE_NAME     "libvmie-dev")
+
+set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE "amd64")
+set(VMIE_DEB_MAINTAINER "Gregory Lirent <opensource@lirent.ru>"
+    CACHE STRING "Debian package Maintainer field")
+set(CPACK_DEBIAN_PACKAGE_MAINTAINER "${VMIE_DEB_MAINTAINER}")
+set(CPACK_DEBIAN_PACKAGE_SECTION "libs")
+set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
+set(CPACK_DEBIAN_FILE_NAME "DEB-DEFAULT")
+
+set(CPACK_COMPONENT_RUNTIME_DESCRIPTION
+    "VM introspection engine (Windows-guest memory introspection) - shared library")
+set(CPACK_COMPONENT_DEV_DESCRIPTION
+    "VM introspection engine (Windows-guest memory introspection) - development files")
+
+# dev depends on the exact runtime version; runtime libc dependency via shlibdeps
+set(CPACK_DEBIAN_DEV_PACKAGE_DEPENDS "libvmie${PROJECT_VERSION_MAJOR} (= ${PROJECT_VERSION})")
+set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
+
+include(CPack)

include/win32.h

@@ -93,18 +93,18 @@ vmie_win32* vmie_win32_open(const char* ram_path, uint64_t low);
 vmie_win32* vmie_win32_open_fd(int fd, uint64_t low);
 
 /* Open a READ-ONLY context over the RAM backing file `fd`, for a consumer that
- * only reads. Unlike vmie_win32_open_fd this does NOT bootstrap (the magic-
+ * only reads. It takes a caller-supplied `kcr3` (kernel cr3 / System DirectoryTableBase)
- * signature handshake needs RW): the caller supplies the address space by passing
+ * and builds the struct-offset profile read-only from the image (no bootstrap
- * a cr3 to each read call. Every read API that takes a cr3 works - the section /
+ * handshake - beacon and ACK are not used). The result has the FULL read
- * function / import / export / callgraph / hook surfaces, gva_read_text, and the
+ * capability: proc_list/proc_modules AND the section / function / import / export
- * generic gva_* and scanner surfaces via vmie_win32_mem(); writes (gva_write) -1
+ * / callgraph / hook surfaces, gva_read_text, and the generic gva_* and scanner
- * because the mapping is PROT_READ. proc_list/proc_modules are NOT available here:
+ * surfaces via vmie_win32_mem(). Any write (gva_write) returns -1 because the
- * they need the bootstrap-recovered profile, which a read-only context does not
+ * mapping is PROT_READ. `fd` is BORROWED (dup()'d internally; the caller's fd
- * carry. `fd` is BORROWED (dup()'d internally; the caller's fd stays valid after
+ * stays valid after this call AND after vmie_win32_close()); an O_RDONLY fd is
- * this call AND after vmie_win32_close()); an O_RDONLY fd is accepted. `low` is
+ * accepted. `low` is the below-4G split, as in vmie_win32_open_fd. Returns a new
- * the below-4G split, as in vmie_win32_open_fd. Returns a new context, or NULL on
+ * context, or NULL if `kcr3` does not resolve a kernel (ntoskrnl not found under
- * dup/fstat/mmap failure. Free with vmie_win32_close(). */
+ * it) or on dup/fstat/mmap failure. Free with vmie_win32_close(). */
-vmie_win32* vmie_win32_open_ro_fd(int fd, uint64_t low);
+vmie_win32* vmie_win32_open_ro_fd(int fd, uint64_t low, uint64_t kcr3);
 
 /* Unmap, close, and free a context. Safe on NULL. After this, every pointer
  * into guest memory obtained through this context is invalid. */

src/engine/win32/host.c

@@ -6,6 +6,9 @@
 
 #define MZ           0x5A4Du
 
+__attribute__((cold))
+static int host_profile_from_cr3(vmie_win32* v, uintptr_t cr3);
+
 /* ---- lifecycle (cold) ---------------------------------------------------- */
 
 __attribute__((cold))
@@ -34,10 +37,12 @@ vmie_win32* vmie_win32_open_fd(int fd, uint64_t low) {
     return v;
 }
 
-/* Read-only context: no bootstrap, the cr3 is supplied per read call. The mem is
+/* Read-only consumer context: maps the backing file PROT_READ and builds the
- * mapped PROT_READ (gpa_from_ro_fd), so every write through it returns -1. */
+ * struct-offset profile from the image under the caller-supplied kcr3 (no
+ * beacon, no cr3 recovery, no ACK write). All read APIs work, incl.
+ * proc_list/proc_modules; writes return -1. */
 __attribute__((cold))
-vmie_win32* vmie_win32_open_ro_fd(int fd, uint64_t low) {
+vmie_win32* vmie_win32_open_ro_fd(int fd, uint64_t low, uint64_t kcr3) {
     vmie_win32* v = calloc(1, sizeof *v);
     if (!v) {
         return NULL;
@@ -46,6 +51,10 @@ vmie_win32* vmie_win32_open_ro_fd(int fd, uint64_t low) {
         free(v);
         return NULL;
     }
+    if (host_profile_from_cr3(v, (uintptr_t)kcr3)) {
+        vmie_win32_close(v);
+        return NULL;
+    }
     return v;
 }
 
@@ -181,6 +190,31 @@ static uint32_t ko_export_rva(vmie_mem* m, uintptr_t cr3, uint64_t kbase, const
     return 0;
 }
 
+__attribute__((cold))
+static int host_profile_from_cr3(vmie_win32* v, uintptr_t cr3) {
+    vmie_mem* m = &v->mem;
+    uint8_t  guid[16];
+    uint32_t age, rva;
+    uint64_t sys_ep, dtb;
+
+    if (find_ntoskrnl(m, cr3, &v->kbase, guid, &age)) {
+        return -3;
+    }
+    rva = ko_export_rva(m, cr3, v->kbase, "PsInitialSystemProcess");
+    if (!rva || gva_read(m, cr3, v->kbase + rva, &sys_ep, 8)) {
+        return -4;
+    }
+    if (profile_build(v, cr3, sys_ep, guid, age)) {
+        return -5;
+    }
+    if (gva_read(m, cr3, sys_ep + v->prof.ep_dtb, &dtb, 8)) {
+        return -6;
+    }
+    v->kcr3    = dtb & PFN_MASK;
+    v->sysproc = sys_ep;
+    return 0;
+}
+
 static void beacon_ack(vmie_mem* m, uint64_t anchor_pa) {
     uint64_t ack = CONTRACT_MAGIC_R;
     gpa_write(m, anchor_pa + offsetof(contract, ack), &ack, 8);
@@ -195,10 +229,6 @@ int host_bootstrap(vmie_win32* v) {
     vmie_mem* m = &v->mem;
     uint64_t anchor_pa, va_self;
     uintptr_t cr3boot;
-    uint32_t rva;
-    uint8_t guid[16];
-    uint32_t age;
-    uint64_t sys_ep;
 
     if (beacon_find(m, &anchor_pa, &va_self)) {
         return -1;
@@ -208,26 +238,11 @@ int host_bootstrap(vmie_win32* v) {
         return -2;
     }
 
-    if (find_ntoskrnl(m, cr3boot, &v->kbase, guid, &age)) {
+    const int rc = host_profile_from_cr3(v, cr3boot);
-        return -3;
+    if (rc) {
+        return rc;
     }
 
-    rva = ko_export_rva(m, cr3boot, v->kbase, "PsInitialSystemProcess");
-    if (!rva || gva_read(m, cr3boot, v->kbase + rva, &sys_ep, 8)) {
-        return -4;
-    }
-
-    if (profile_build(v, cr3boot, sys_ep, guid, age)) {
-        return -5;
-    }
-
-    uint64_t dtb;
-    if (gva_read(m, cr3boot, sys_ep + v->prof.ep_dtb, &dtb, 8)) {
-        return -6;
-    }
-    v->kcr3    = dtb & PFN_MASK;
-    v->sysproc = sys_ep;
-
     beacon_ack(m, anchor_pa);
     return 0;
 }