@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/references/native/InsightServerInit.java

@@ -0,0 +1,62 @@
+package ghidra.server;
+
+import com.google.gson.Gson;
+import generic.hash.HashUtilities;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.remote.User;
+import java.nio.channels.FileChannel;
+import java.nio.file.*;
+import java.util.*;
+
+/** Initialize only the facade's owned local storage, before any network listener exists. */
+class InsightServerInit {
+  public static void main(String[] args) {
+    var output = System.out; System.setOut(System.err);
+    try {
+      if(args.length!=4) throw new IllegalArgumentException();
+      Path root=Path.of(args[0]).toRealPath();
+      String repository=args[1], publisher=args[2], reader=args[3];
+      if(publisher.equals(reader) || !repository.startsWith("insight_")) throw new IllegalArgumentException();
+      try(var channel=FileChannel.open(root.resolveSibling("server.lock"),StandardOpenOption.CREATE,StandardOpenOption.WRITE);
+          var lock=channel.tryLock()) {
+        if(lock==null) throw new IllegalStateException("Owned server is already running");
+        Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+        RepositoryManager manager=new RepositoryManager(root.toFile(),true,0,false);
+        try {
+          UserManager users=manager.getUserManager();
+          for(String role:List.of("PUBLISHER","READER")) {
+            String user=role.equals("PUBLISHER")?publisher:reader;
+            String secret=System.getenv("INSIGHT_"+role+"_PASSWORD");
+            if(secret==null || secret.length()<32) throw new SecurityException();
+            char[] password=secret.toCharArray();
+            try {
+              if(!users.isValidUser(user)) {
+                char[] hash=HashUtilities.getSaltedHash(HashUtilities.SHA256_ALGORITHM,password);
+                try { users.addUser(user,hash.clone()); users.setPassword(user,hash.clone(),false); }
+                finally { Arrays.fill(hash,'\0'); }
+              }
+              users.authenticateUser(user,password);
+            } finally { Arrays.fill(password,'\0'); }
+          }
+          Repository model=manager.getRepository(publisher,repository);
+          if(model==null) {
+            model=manager.createRepository(publisher,repository);
+            model.setUserList(publisher,new User[]{new User(publisher,User.ADMIN),new User(reader,User.READ_ONLY)},false);
+          }
+          var permissions=model.getUserList(publisher);
+          if(permissions.length!=2 || model.anonymousAccessAllowed() ||
+              Arrays.stream(permissions).noneMatch(user->user.getName().equals(reader)&&user.isReadOnly()) ||
+              Arrays.stream(permissions).noneMatch(user->user.getName().equals(publisher)&&user.isAdmin()))
+            throw new SecurityException("Owned repository authority changed");
+        } finally { manager.dispose(); }
+      }
+      output.println(new Gson().toJson(Map.of("state","ready","repository",repository,"readerReadOnly",true,"publisherAdmin",true)));
+      System.exit(0);
+    } catch(Throwable failure) {
+      failure.printStackTrace(System.err);
+      output.println("{\"state\":\"failed\",\"error\":\"owned_server_initialization_failed\"}"); System.exit(1);
+    }
+  }
+}

package/references/native/InsightServerMain.java

@@ -0,0 +1,43 @@
+import com.google.gson.Gson;
+import com.sun.net.httpserver.HttpServer;
+import ghidra.net.ApplicationKeyManagerFactory;
+import ghidra.server.remote.GhidraServer;
+import java.net.InetSocketAddress;
+import java.nio.channels.FileChannel;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.*;
+import java.security.MessageDigest;
+import java.util.*;
+
+/** Owned loopback server with an authenticated identity probe, not an administration API. */
+class InsightServerMain {
+  public static void main(String[] args) throws Exception {
+    if(args.length!=5) throw new IllegalArgumentException();
+    Path root=Path.of(args[0]).toRealPath();
+    int port=Integer.parseInt(args[1]), healthPort=Integer.parseInt(args[2]);
+    String instance=args[3], keystore=args[4];
+    String token=System.getenv("INSIGHT_SERVER_TOKEN"), password=System.getenv("INSIGHT_KEYSTORE_PASSWORD");
+    if(token==null || token.length()<32 || password==null || password.length()<32) throw new SecurityException();
+    FileChannel channel=FileChannel.open(root.resolveSibling("server.lock"),StandardOpenOption.CREATE,StandardOpenOption.WRITE);
+    var lock=channel.tryLock(); if(lock==null) throw new IllegalStateException("Owned server already running");
+    System.setProperty("ghidra.keystore",keystore);
+    ApplicationKeyManagerFactory.setKeyStorePasswordProvider((path,retry)->password.toCharArray());
+    GhidraServer.main(new String[]{"-i","127.0.0.1","-ip","127.0.0.1","-p"+port,"-a0","-e0","-u",root.toString()});
+    HttpServer health=HttpServer.create(new InetSocketAddress("127.0.0.1",healthPort),4);
+    byte[] authorization=("Bearer "+token).getBytes(StandardCharsets.UTF_8);
+    health.createContext("/identity",exchange->{
+      String supplied=exchange.getRequestHeaders().getFirst("Authorization");
+      if(!exchange.getRequestMethod().equals("GET") || !exchange.getRequestURI().toString().equals("/identity") ||
+          supplied==null || !MessageDigest.isEqual(authorization,supplied.getBytes(StandardCharsets.UTF_8))) {
+        exchange.sendResponseHeaders(403,-1); exchange.close(); return;
+      }
+      byte[] response=new Gson().toJson(Map.of("pid",ProcessHandle.current().pid(),"instance",instance,"port",port)).getBytes(StandardCharsets.UTF_8);
+      exchange.getResponseHeaders().set("Content-Type","application/json");
+      exchange.sendResponseHeaders(200,response.length); exchange.getResponseBody().write(response); exchange.close();
+    });
+    health.start();
+    Runtime.getRuntime().addShutdownHook(new Thread(()->{
+      health.stop(0); try {lock.release();channel.close();} catch(Exception ignored){}
+    }));
+  }
+}

package/references/native/InsightServerProbe.java

@@ -0,0 +1,29 @@
+import com.google.gson.Gson;
+import com.xebyte.headless.GhidraServerManager;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import java.util.*;
+
+/** Verify actual repository credentials and permissions, without creating or changing anything. */
+class InsightServerProbe {
+  public static void main(String[] args) {
+    var output=System.out; System.setOut(System.err);
+    try {
+      if(args.length!=2 || !Set.of("reader","publisher").contains(args[1])) throw new IllegalArgumentException();
+      Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+      GhidraServerManager manager=new GhidraServerManager(); manager.connect();
+      var repository=manager.server().getRepository(args[0]); repository.connect();
+      var user=repository.getUser();
+      if(user==null || !user.getName().equals(System.getenv("GHIDRA_SERVER_USER")) ||
+          (args[1].equals("reader")?!user.isReadOnly():!user.hasWritePermission())) throw new SecurityException();
+      int permission=user.getPermissionType();
+      repository.disconnect(); manager.server().disconnect();
+      output.println(new Gson().toJson(Map.of("repository",args[0],"role",args[1],"permission",permission)));
+      System.exit(0);
+    } catch(Throwable failure) {
+      failure.printStackTrace(System.err);
+      output.println("{\"error\":\"repository_authority_not_verified\"}"); System.exit(1);
+    }
+  }
+}

package/references/native/InsightSnapshotFields.java

@@ -0,0 +1,68 @@
+import com.google.gson.*;
+import db.DBHandle;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.data.OpenMode;
+import ghidra.framework.store.db.PackedDatabase;
+import ghidra.program.database.ProgramDB;
+import ghidra.program.model.listing.CodeUnit;
+import ghidra.util.task.TaskMonitor;
+import java.nio.file.*;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.*;
+
+/** Read scalar values and conservative dependencies from an immutable saved program. */
+class InsightSnapshotFields {
+  static final Map<String,Integer> kinds=Map.of("comment.eol",CodeUnit.EOL_COMMENT,"comment.pre",CodeUnit.PRE_COMMENT,
+    "comment.post",CodeUnit.POST_COMMENT,"comment.plate",CodeUnit.PLATE_COMMENT,"comment.repeatable",CodeUnit.REPEATABLE_COMMENT);
+  public static void main(String[] args) {
+    var output=System.out;System.setOut(System.err);
+    try {
+      if(args.length!=2)throw new IllegalArgumentException();
+      String input=Files.readString(Path.of(args[1]));if(input.length()>1048576)throw new IllegalArgumentException();
+      JsonArray requests=JsonParser.parseString(input).getAsJsonArray();if(requests.size()>5000)throw new IllegalArgumentException();
+      Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+      DBHandle db=PackedDatabase.getPackedDatabase(Path.of(args[0]).toFile(),true,TaskMonitor.DUMMY).open(TaskMonitor.DUMMY);
+      Object consumer=new Object();ProgramDB program=new ProgramDB(db,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,consumer);
+      Map<String,Object> values=new LinkedHashMap<>();
+      try {
+        for(JsonElement item:requests) {
+          JsonObject request=item.getAsJsonObject();String address=request.get("address").getAsString(),field=request.get("field").getAsString();
+          if(!field.equals("function.name")&&!kinds.containsKey(field))throw new IllegalArgumentException();
+          var at=program.getAddressFactory().getAddress(address);
+          var block=at==null?null:program.getMemory().getBlock(at);
+          var function=at==null?null:field.equals("function.name")?program.getFunctionManager().getFunctionAt(at):program.getFunctionManager().getFunctionContaining(at);
+          boolean exists=block!=null&&(!field.equals("function.name")||function!=null);
+          String value=field.equals("function.name")?(function==null?null:function.getName()):
+            (at==null?null:program.getListing().getComment(kinds.get(field),at));
+          Map<String,Object> dependency=new LinkedHashMap<>();
+          if(exists) {
+            dependency.put("space",at.getAddressSpace().getName());
+            dependency.put("blockStart",block.getStart().toString());dependency.put("blockEnd",block.getEnd().toString());
+            dependency.put("blockType",block.getType().toString());
+            byte[] bytes=new byte[16];int read=0;
+            if(block.isInitialized()) {
+              long available=block.getEnd().subtract(at)+1;
+              read=program.getMemory().getBytes(at,bytes,0,(int)Math.min(16,available));
+            }
+            dependency.put("bytes",HexFormat.of().formatHex(Arrays.copyOf(bytes,read)));
+            if(function!=null) {
+              dependency.put("functionId",function.getID());dependency.put("body",function.getBody().toString());
+              dependency.put("namespace",function.getParentNamespace().getName(true));
+              dependency.put("returnType",function.getReturnType().getPathName());
+              dependency.put("callingConvention",Objects.toString(function.getCallingConventionName(),""));
+              dependency.put("parameters",Arrays.stream(function.getParameters()).map(parameter->parameter.getDataType().getPathName()).toList());
+            }
+          }
+          String anchor=HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(new Gson().toJson(dependency).getBytes(StandardCharsets.UTF_8)));
+          Map<String,Object> observed=new LinkedHashMap<>();observed.put("value",value);observed.put("exists",exists);observed.put("dependency",anchor);
+          values.put(address+"@"+field,observed);
+        }
+      }finally{program.release(consumer);}
+      output.println(new GsonBuilder().serializeNulls().create().toJson(Map.of("fields",values)));
+      System.exit(0);
+    }catch(Throwable failure){failure.printStackTrace(System.err);output.println("{\"error\":\"snapshot_inspection_failed\"}");System.exit(1);}
+  }
+}

package/references/native/InsightSnapshotInspect.java

@@ -0,0 +1,189 @@
+import com.google.gson.*;
+import com.xebyte.core.ServiceUtils;
+import db.DBHandle;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.data.OpenMode;
+import ghidra.framework.store.db.PackedDatabase;
+import ghidra.program.database.ProgramDB;
+import ghidra.program.model.data.*;
+import ghidra.util.task.TaskMonitor;
+import java.nio.file.*;
+import java.util.*;
+
+/** Inspect the committed private snapshot, rather than trusting a mutation acknowledgment. */
+class InsightSnapshotInspect {
+  static String string(JsonObject request,String name) {return request.has(name)?request.get(name).getAsString():"";}
+  static Map<String,Object> type(DataType value) {
+    Map<String,Object> out=new LinkedHashMap<>();out.put("name",value.getName());out.put("path",value.getPathName());
+    out.put("size",value.getLength());out.put("category",value.getCategoryPath().getPath());out.put("kind",value.getClass().getSimpleName());
+    if(value instanceof Composite composite) {
+      List<Object> fields=new ArrayList<>();
+      for(var field:composite.getDefinedComponents()) {Map<String,Object> f=new LinkedHashMap<>();
+        f.put("name",field.getFieldName());f.put("type",field.getDataType().getName());f.put("offset",field.getOffset());f.put("size",field.getLength());fields.add(f);}
+      out.put("fields",fields);
+    }
+    if(value instanceof ghidra.program.model.data.Enum enumeration) {
+      Map<String,Object> members=new LinkedHashMap<>();for(String name:enumeration.getNames())members.put(name,Long.toString(enumeration.getValue(name)));
+      out.put("values",members);
+    }
+    if(value instanceof FunctionDefinition function) {
+      out.put("returnType",function.getReturnType().getName());
+      out.put("arguments",Arrays.stream(function.getArguments()).map(arg->arg.getDataType().getName()).toList());
+    }
+    if(value instanceof Array array){out.put("elementType",array.getDataType().getName());out.put("elementCount",array.getNumElements());}
+    if(value instanceof Pointer pointer)out.put("pointerBase",pointer.getDataType()==null?"void":pointer.getDataType().getName());
+    if(value instanceof TypeDef alias)out.put("typedefBase",alias.getBaseDataType().getName());
+    return out;
+  }
+  static Object inspect(ProgramDB program,JsonObject request) throws Exception {
+    String kind=string(request,"kind"),name=string(request,"name"),address=string(request,"address");
+    if(kind.equals("sdk"))return insight.InsightSdkTools.verify(program,string(request,"operation"),request.getAsJsonObject("parameters"),TaskMonitor.DUMMY);
+    var at=address.isEmpty()?null:program.getAddressFactory().getAddress(address);
+    if(!address.isEmpty()&&at==null)throw new IllegalArgumentException("Invalid inspection address");
+    if(kind.equals("debugger_bookmarks")){
+      List<String> rows=new ArrayList<>();var gson=new Gson();
+      for(String type:List.of("BreakpointEnabled","BreakpointDisabled")){
+        var bookmarks=program.getBookmarkManager().getBookmarksIterator(type);
+        while(bookmarks.hasNext()){if(rows.size()>=100000)throw new IllegalArgumentException("Debugger bookmark inventory too large");var bookmark=bookmarks.next();
+          rows.add(gson.toJson(Arrays.asList(bookmark.getAddress().toString(),type,bookmark.getCategory(),bookmark.getComment())));}
+      }
+      Collections.sort(rows);byte[] hash=java.security.MessageDigest.getInstance("SHA-256").digest(gson.toJson(rows).getBytes(java.nio.charset.StandardCharsets.UTF_8));
+      return Map.of("count",rows.size(),"fingerprint",HexFormat.of().formatHex(hash));
+    }
+    if(kind.equals("type")||kind.equals("resolve_type")) {
+      DataType value=kind.equals("resolve_type")?ServiceUtils.resolveDataType(program.getDataTypeManager(),name):
+        ServiceUtils.findDataTypeByNameInAllCategories(program.getDataTypeManager(),name);
+      return value==null?Map.of("exists",false):Map.of("exists",true,"type",type(value));
+    }
+    if(kind.equals("data")) {
+      if(at==null)throw new IllegalArgumentException();var data=program.getListing().getDefinedDataAt(at);
+      return data==null?Map.of("exists",false):Map.of("exists",true,"type",data.getDataType().getName(),"size",data.getLength(),"details",type(data.getDataType()),"isString",data.hasStringValue());
+    }
+    if(kind.equals("import_check")) {
+      try(var expected=new StandAloneDataTypeManager("ExpectedImport",program.getDataTypeManager().getDataOrganization())) {
+        int transaction=expected.startTransaction("Parse expected types");
+        var parser=new ghidra.app.util.cparser.C.CParser(expected,true,new DataTypeManager[]{program.getDataTypeManager()});
+        try{parser.parse(string(request,"source"));}finally{expected.endTransaction(transaction,true);}
+        if(!parser.didParseSucceed())throw new IllegalArgumentException("Expected import did not parse");
+        List<Object> types=new ArrayList<>();var iter=expected.getAllDataTypes();
+        while(iter.hasNext()){if(types.size()>10000)throw new IllegalArgumentException("Import too large");var wanted=iter.next();
+          var actual=program.getDataTypeManager().getDataType(wanted.getPathName());
+          types.add(Map.of("name",wanted.getName(),"path",wanted.getPathName(),"matches",actual!=null&&wanted.isEquivalent(actual),"expected",type(wanted),"actual",actual==null?Map.of():type(actual)));}
+        return Map.of("types",types,"count",types.size());
+      }
+    }
+    if(kind.equals("category"))return Map.of("exists",program.getDataTypeManager().getCategory(new CategoryPath(name))!=null);
+    if(kind.equals("memory")) {
+      var memory=program.getMemory();var block=name.isEmpty()?memory.getBlock(at):memory.getBlock(name);
+      if(block==null)return Map.of("exists",false);
+      Map<String,Object> out=new LinkedHashMap<>();out.put("exists",true);out.put("name",block.getName());out.put("start",block.getStart().toString());
+      out.put("size",block.getSize());out.put("read",block.isRead());out.put("write",block.isWrite());out.put("execute",block.isExecute());
+      out.put("volatile",block.isVolatile());out.put("initialized",block.isInitialized());out.put("overlay",block.isOverlay());out.put("comment",block.getComment());
+      out.put("physicalStart",block.getStart().getPhysicalAddress().toString());
+      if(request.has("digest_bytes")&&request.get("digest_bytes").getAsBoolean()) {
+        if(block.getSize()>16777216L)throw new IllegalArgumentException("Memory digest exceeds 16 MiB verification bound");
+        String digest=null;if(block.isInitialized()) {var hash=java.security.MessageDigest.getInstance("SHA-256");long offset=0;
+          while(offset<block.getSize()){int count=(int)Math.min(65536,block.getSize()-offset);byte[] bytes=new byte[count];int read=memory.getBytes(block.getStart().add(offset),bytes);if(read!=count)throw new IllegalStateException("Incomplete saved memory read");hash.update(bytes);offset+=count;}
+          digest=java.util.HexFormat.of().formatHex(hash.digest());}out.put("sha256",digest);
+      }
+      return out;
+    }
+    if(kind.equals("metadata"))return Map.of("imageBase",program.getImageBase().toString(),"sha256",program.getExecutableSHA256(),
+      "analyzed",ghidra.program.util.GhidraProgramUtilities.isAnalyzed(program),"functionCount",program.getFunctionManager().getFunctionCount());
+    if(kind.equals("function_tags")) {
+      return Map.of("tags",program.getFunctionManager().getFunctionTagManager().getAllFunctionTags().stream()
+        .map(tag->Map.of("name",tag.getName(),"comment",Objects.toString(tag.getComment(),""))).toList());
+    }
+    if(kind.equals("function")) {
+      var functions=program.getFunctionManager();var function=at==null?null:functions.getFunctionAt(at);
+      if(function==null&&!name.isEmpty()){var iter=functions.getFunctions(true);while(iter.hasNext()){var candidate=iter.next();
+        if(candidate.getName().equals(name)||candidate.getName(true).equals(name)){if(function!=null)throw new IllegalArgumentException("Ambiguous function");function=candidate;}}}
+      if(function==null)return Map.of("exists",false);
+      Map<String,Object> out=new LinkedHashMap<>();out.put("exists",true);out.put("name",function.getName());out.put("address",function.getEntryPoint().toString());
+      out.put("returnType",function.getReturnType().getName());out.put("signature",function.getSignature().getPrototypeString());
+      out.put("defaultCallingConvention",program.getCompilerSpec().getDefaultCallingConvention().getName());
+      out.put("namespace",function.getParentNamespace().getName(true));out.put("noReturn",function.hasNoReturn());out.put("callingConvention",function.getCallingConventionName());
+      List<Object> variables=new ArrayList<>();for(var variable:function.getAllVariables())variables.add(Map.of("name",variable.getName(),"type",variable.getDataType().getName(),"storage",variable.getVariableStorage().toString(),"parameter",variable instanceof ghidra.program.model.listing.Parameter));
+      out.put("variables",variables);out.put("parameters",Arrays.stream(function.getParameters()).map(param->Map.of("name",param.getName(),"type",param.getDataType().getName(),"storage",param.getVariableStorage().toString(),"auto",param.isAutoParameter())).toList());
+      out.put("tags",function.getTags().stream().map(tag->Map.of("name",tag.getName(),"comment",Objects.toString(tag.getComment(),""))).toList());
+      String prototype=string(request,"prototype");if(!prototype.isEmpty()){
+        String[] normalized=com.xebyte.core.FunctionService.extractCallingConvention(prototype);
+        var expected=new ghidra.app.util.parser.FunctionSignatureParser(program.getDataTypeManager(),null).parse(function.getSignature(),normalized[1]);
+        out.put("expectedPrototype",Map.of("name",expected.getName(),"returnType",expected.getReturnType().getName(),
+          "inlineCallingConvention",normalized[0],"parameters",Arrays.stream(expected.getArguments()).map(param->Map.of("name",Objects.toString(param.getName(),""),"type",param.getDataType().getName())).toList()));}
+      return out;
+    }
+    if(kind.equals("instructions")) {
+      if(at==null)throw new IllegalArgumentException();var instruction=program.getListing().getInstructionAt(at);
+      return instruction==null?Map.of("exists",false):Map.of("exists",true,"flowOverride",instruction.getFlowOverride().toString(),"length",instruction.getLength(),"mnemonic",instruction.getMnemonicString());
+    }
+    if(kind.equals("instruction_range")) {
+      if(at==null)throw new IllegalArgumentException();var end=program.getAddressFactory().getAddress(string(request,"end_address"));
+      if(end==null||!at.getAddressSpace().equals(end.getAddressSpace())||end.compareTo(at)<=0)throw new IllegalArgumentException("Invalid instruction seed");
+      long count=0;var iter=program.getListing().getInstructions(new ghidra.program.model.address.AddressSet(at,end.subtract(1)),true);
+      while(iter.hasNext()){iter.next();if(++count>1000000)throw new IllegalArgumentException("Instruction seed too large");}
+      return Map.of("count",count);
+    }
+    if(kind.equals("symbols")) {
+      List<Object> symbols=new ArrayList<>();
+      if(at!=null)for(var symbol:program.getSymbolTable().getSymbols(at))symbols.add(Map.of("name",symbol.getName(),"namespace",symbol.getParentNamespace().getName(true),"primary",symbol.isPrimary(),"kind",symbol.getSymbolType().toString()));
+      else {var iter=program.getSymbolTable().getSymbols(name);while(iter.hasNext()){var s=iter.next();symbols.add(Map.of("name",s.getName(),"address",s.getAddress().toString(),"primary",s.isPrimary()));}}
+      return Map.of("symbols",symbols);
+    }
+    if(kind.equals("references")) {
+      if(at==null)throw new IllegalArgumentException();List<Object> refs=new ArrayList<>();
+      for(var ref:program.getReferenceManager().getReferencesFrom(at))refs.add(Map.of("to",ref.getToAddress().toString(),"type",ref.getReferenceType().toString(),"operand",ref.getOperandIndex(),"source",ref.getSource().toString()));
+      return Map.of("references",refs);
+    }
+    if(kind.equals("property")) {
+      var map=program.getUsrPropertyManager().getPropertyMap(name);
+      if(map==null)return Map.of("exists",false);
+      Map<String,Object> out=new LinkedHashMap<>();out.put("exists",true);out.put("type",map.getClass().getSimpleName());
+      if(at!=null) {boolean has=map.hasProperty(at);out.put("hasValue",has);
+        if(has){Object value=map instanceof ghidra.program.model.util.StringPropertyMap m?m.getString(at):
+          map instanceof ghidra.program.model.util.IntPropertyMap m?Integer.toString(m.getInt(at)):
+          map instanceof ghidra.program.model.util.LongPropertyMap m?Long.toString(m.getLong(at)):null;out.put("value",value);}}
+      return out;
+    }
+    if(kind.equals("option")) {
+      var options=program.getOptions(string(request,"group"));boolean exists=options.contains(name);
+      Map<String,Object> out=new LinkedHashMap<>();out.put("exists",exists);if(exists){out.put("type",options.getType(name).toString());out.put("value",Objects.toString(options.getObject(name,null),null));}return out;
+    }
+    if(kind.equals("bookmarks")) {
+      if(at==null)throw new IllegalArgumentException();List<Object> entries=new ArrayList<>();
+      for(var mark:program.getBookmarkManager().getBookmarks(at))entries.add(Map.of("category",mark.getCategory(),"comment",mark.getComment(),"type",mark.getTypeString()));
+      return Map.of("bookmarks",entries);
+    }
+    if(kind.equals("comments")) {
+      if(at==null)throw new IllegalArgumentException();Map<String,Object> result=new LinkedHashMap<>();
+      result.put("eol",program.getListing().getComment(ghidra.program.model.listing.CodeUnit.EOL_COMMENT,at));
+      result.put("pre",program.getListing().getComment(ghidra.program.model.listing.CodeUnit.PRE_COMMENT,at));
+      result.put("plate",program.getListing().getComment(ghidra.program.model.listing.CodeUnit.PLATE_COMMENT,at));return result;
+    }
+    if(kind.equals("function_comments")) {
+      var function=at==null?null:program.getFunctionManager().getFunctionAt(at);
+      if(function==null&&!name.isEmpty()){var iter=program.getFunctionManager().getFunctions(true);while(iter.hasNext()){var candidate=iter.next();
+        if(candidate.getName().equals(name)){if(function!=null)throw new IllegalArgumentException("Ambiguous function");function=candidate;}}}
+      if(function==null)throw new IllegalArgumentException("Function missing");
+      List<Object> comments=new ArrayList<>();var iter=program.getListing().getInstructions(function.getBody(),true);int count=0;
+      while(iter.hasNext()){if(++count>100000)throw new IllegalArgumentException("Function too large for comment inspection");var instruction=iter.next();
+        for(int type:new int[]{ghidra.program.model.listing.CodeUnit.PRE_COMMENT,ghidra.program.model.listing.CodeUnit.EOL_COMMENT}){
+          String comment=program.getListing().getComment(type,instruction.getAddress());if(comment!=null)comments.add(Map.of("kind",type==ghidra.program.model.listing.CodeUnit.EOL_COMMENT?"eol":"pre","address",instruction.getAddress().toString(),"text",comment));}}
+      Map<String,Object> result=new LinkedHashMap<>();result.put("plate",function.getComment());result.put("comments",comments);return result;
+    }
+    throw new IllegalArgumentException("Unsupported saved-state inspection");
+  }
+  public static void main(String[] args) {
+    var output=System.out;System.setOut(System.err);
+    try {
+      if(args.length!=2)throw new IllegalArgumentException();String encoded=Files.readString(Path.of(args[1]));if(encoded.length()>65536)throw new IllegalArgumentException();
+      Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+      DBHandle db=PackedDatabase.getPackedDatabase(Path.of(args[0]).toFile(),true,TaskMonitor.DUMMY).open(TaskMonitor.DUMMY);
+      Object consumer=new Object();ProgramDB program=new ProgramDB(db,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,consumer);
+      try {output.println(new GsonBuilder().serializeNulls().create().toJson(Map.of("value",inspect(program,JsonParser.parseString(encoded).getAsJsonObject()))));}
+      finally {program.release(consumer);}System.exit(0);
+    }catch(Throwable failure){failure.printStackTrace(System.err);output.println("{\"error\":\"saved_inspection_failed\"}");System.exit(1);}
+  }
+}

package/references/native/InsightSnapshotPublisher.java

@@ -0,0 +1,123 @@
+package db;
+
+import com.google.gson.Gson;
+import com.xebyte.headless.GhidraServerManager;
+import db.buffers.ManagedBufferFile;
+import db.buffers.LocalBufferFile;
+import db.buffers.InsightBlockTransfer;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.data.OpenMode;
+import ghidra.framework.store.CheckoutType;
+import ghidra.framework.store.db.PackedDatabase;
+import ghidra.program.database.ProgramDB;
+import ghidra.program.model.listing.ProgramChangeSet;
+import ghidra.util.task.TaskMonitor;
+import java.io.*;
+import java.nio.file.*;
+import java.util.*;
+
+/** Publish one verified saved private program through the pinned native DB transfer protocol.
+ * Package db grants access to the pinned DBHandle saved source buffers without reflection.
+ * The caller owns this repository and must journal intent before invoking this helper. */
+class InsightSnapshotPublisher {
+  static void receipt(Path file, Map<String,Object> state) throws Exception {
+    Path temporary = file.resolveSibling(file.getFileName() + ".new");
+    try (FileOutputStream stream = new FileOutputStream(temporary.toFile())) {
+      stream.write(new Gson().toJson(state).getBytes(java.nio.charset.StandardCharsets.UTF_8));
+      stream.getFD().sync();
+    }
+    Files.move(temporary, file, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);
+  }
+  public static void main(String[] args) {
+    PrintStream output = System.out;
+    System.setOut(System.err);
+    Map<String,Object> state = new LinkedHashMap<>();
+    try {
+      if (args.length != 7) throw new IllegalArgumentException("Expected seven publication arguments");
+      String repositoryName=args[0], path=args[1], marker=args[4];
+      int expected=Integer.parseInt(args[3]); Path journal=Path.of(args[5]);
+      if (!path.startsWith("/") || path.indexOf('/',1)>=0 || !marker.matches("insight merge q_[a-f0-9-]{36}")) throw new IllegalArgumentException();
+      Application.initializeApplication(new GhidraApplicationLayout(), new HeadlessGhidraApplicationConfiguration());
+      GhidraServerManager manager=new GhidraServerManager(); manager.connect();
+      var repository=manager.server().getRepository(repositoryName); repository.connect();
+      var user=repository.getUser();
+      if (user==null || !user.hasWritePermission() || !user.getName().equals(System.getenv("GHIDRA_SERVER_USER"))) throw new SecurityException();
+      String folder="/", name=path.substring(1);
+      state.put("repository",repositoryName);state.put("path",path);state.put("marker",marker);state.put("baseline",expected);
+      if (repository.getItem(folder,name).getVersion()!=expected) {
+        output.println("{\"state\":\"conflict\",\"applied\":0}"); System.exit(2);
+      }
+      long databaseId;String expectedFingerprint;
+      var checkout=repository.checkout(folder,name,CheckoutType.EXCLUSIVE,journal.getParent().toString());
+      if (checkout==null) throw new IllegalStateException("Exclusive checkout denied");
+      state.put("checkoutId",checkout.getCheckoutId()); state.put("baseline",expected); state.put("phase","checkout"); receipt(journal,state);
+      if (checkout.getCheckoutVersion()!=expected || repository.getItem(folder,name).getVersion()!=expected) throw new IllegalStateException("Baseline changed before exclusive ownership");
+      ManagedBufferFile remote=repository.openDatabase(folder,name,checkout.getCheckoutId());
+      boolean completed=false;
+      try {
+        state.put("phase","commit_intent"); receipt(journal,state);
+        PackedDatabase packed=PackedDatabase.getPackedDatabase(new File(args[2]),true,TaskMonitor.DUMMY);
+        DBHandle snapshot=packed.open(TaskMonitor.DUMMY);
+        databaseId=snapshot.getDatabaseId();
+        expectedFingerprint=InsightBlockTransfer.fingerprint(snapshot.getBufferMgr().getSourceFile());
+        Object snapshotConsumer=new Object();
+        ProgramDB snapshotProgram=new ProgramDB(snapshot,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,snapshotConsumer);
+        if (!args[6].equals(snapshotProgram.getExecutableSHA256())) throw new SecurityException("Snapshot source identity changed");
+        ProgramChangeSet changes=(ProgramChangeSet)snapshotProgram.getChangeSet();
+        snapshotProgram.getChangeSet().startTransaction();
+        try {
+          changes.add(snapshotProgram.getMemory());
+          var dataTypes=snapshotProgram.getDataTypeManager().getAllDataTypes();
+          while(dataTypes.hasNext()) changes.dataTypeChanged(snapshotProgram.getDataTypeManager().getID(dataTypes.next()));
+          var symbols=snapshotProgram.getSymbolTable().getAllSymbols(true);
+          while(symbols.hasNext()) changes.symbolChanged(symbols.next().getID());
+        } finally { snapshotProgram.getChangeSet().endTransaction(true); }
+        ManagedBufferFile save=remote.getSaveFile();
+        if (save==null) throw new IllegalStateException("Save buffer denied");
+        save.setVersionComment(marker);
+        try {
+          InsightBlockTransfer.copy((LocalBufferFile)snapshot.getBufferMgr().getSourceFile(),save);
+          var changeFile=remote.getSaveChangeDataFile();
+          if(changeFile==null) throw new IllegalStateException("Native change-set buffer missing");
+          DBHandle changeDb=new DBHandle();
+          try {
+            snapshotProgram.getChangeSet().write(changeDb,false);
+            changeDb.saveAs(changeFile,false,TaskMonitor.DUMMY);
+          } finally { changeDb.close(); changeFile.dispose(); }
+        } finally { snapshotProgram.release(snapshotConsumer); }
+        remote.saveCompleted(true); completed=true;
+        save.dispose();
+        state.put("phase","committed"); receipt(journal,state);
+      } finally {
+        remote.dispose();
+        if (!completed) state.put("phase","unknown");
+      }
+      var versions=repository.getVersions(folder,name);
+      long matches=Arrays.stream(versions).filter(v->marker.equals(v.getComment())).count();
+      int actual=repository.getItem(folder,name).getVersion();
+      if (matches!=1 || actual!=expected+1) throw new IllegalStateException("Publication history does not establish outcome");
+      DBHandle readback=new DBHandle(repository.openDatabase(folder,name,actual,-1));
+      try {
+        if (readback.getDatabaseId()!=databaseId) throw new IllegalStateException("Saved snapshot database ID changed");
+        if(!expectedFingerprint.equals(InsightBlockTransfer.fingerprint(readback.getBufferMgr().getSourceFile())))
+          throw new IllegalStateException("Published database buffers differ from the verified saved snapshot");
+        Object consumer=new Object();
+        ProgramDB program=new ProgramDB(readback,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,consumer);
+        program.release(consumer);
+      } finally { readback.close(); }
+      repository.terminateCheckout(folder,name,checkout.getCheckoutId(),false);
+      if (Arrays.stream(repository.getCheckouts(folder,name)).anyMatch(c->c.getCheckoutId()==checkout.getCheckoutId())) throw new IllegalStateException("Owned checkout not released");
+      state.put("phase","released"); state.put("version",actual); receipt(journal,state);
+      repository.disconnect(); manager.server().disconnect();
+      output.println(new Gson().toJson(Map.of("state","published","version",actual,"snapshotDatabaseIdPreserved",true,"snapshotBuffersVerified",true,"ownedCheckoutReleased",true)));
+      System.exit(0);
+    } catch (Throwable failure) {
+      System.err.println(failure.getClass().getName()+": "+failure.getMessage());
+      failure.printStackTrace(System.err);
+      output.println(new Gson().toJson(Map.of("state","failed","phase",state.getOrDefault("phase","setup"))));
+      System.exit(1);
+    }
+  }
+}

package/references/native/InsightStartDebugger.java

@@ -0,0 +1,28 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.app.services.DebuggerTraceManagerService;
+import ghidra.app.services.ProgramManager;
+import ghidra.framework.plugintool.PluginTool;
+import javax.swing.SwingUtilities;
+import java.util.concurrent.atomic.AtomicReference;
+
+/** Idempotent resource startup in this script's owned project; does not launch a debuggee. */
+public class InsightStartDebugger extends GhidraScript {
+  void prepare(PluginTool tool)throws Exception{
+    tool.getService(DebuggerTraceManagerService.class).setAutoCloseOnTerminate(false);
+    var programs=tool.getService(ProgramManager.class);if(programs==null||currentProgram==null)return;
+    Runnable open=()->{if(!java.util.Arrays.asList(programs.getAllOpenPrograms()).contains(currentProgram))programs.openProgram(currentProgram);};
+    if(SwingUtilities.isEventDispatchThread())open.run();else SwingUtilities.invokeAndWait(open);
+  }
+  @Override public void run()throws Exception{
+    var project=state.getProject();if(project==null)throw new IllegalStateException("Owned project missing");
+    var manager=project.getToolManager();
+    for(PluginTool tool:manager.getRunningTools())if(tool.getService(DebuggerTraceManagerService.class)!=null){prepare(tool);println("INSIGHT_DEBUGGER_READY");return;}
+    var template=project.getLocalToolChest().getToolTemplate("Debugger");if(template==null)throw new IllegalStateException("Debugger tool template missing");
+    AtomicReference<PluginTool> started=new AtomicReference<>();
+    Runnable start=()->started.set(manager.getActiveWorkspace().runTool(template));
+    if(SwingUtilities.isEventDispatchThread())start.run();else SwingUtilities.invokeAndWait(start);
+    if(started.get()==null||started.get().getService(DebuggerTraceManagerService.class)==null)throw new IllegalStateException("Debugger services unavailable");
+    prepare(started.get());
+    println("INSIGHT_DEBUGGER_READY");
+  }
+}

package/references/native/InsightStopDebugger.java

@@ -0,0 +1,20 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.app.services.DebuggerTraceManagerService;
+import ghidra.app.services.DebuggerTargetService;
+import ghidra.framework.plugintool.PluginTool;
+import java.util.concurrent.TimeUnit;
+
+/** Close only target objects reached through this owned project's debugger services. */
+public class InsightStopDebugger extends GhidraScript {
+  @Override public void run()throws Exception{
+    var project=state.getProject();if(project==null)throw new IllegalStateException("Owned project missing");
+    for(PluginTool tool:project.getToolManager().getRunningTools()){
+      var traces=tool.getService(DebuggerTraceManagerService.class);var targets=tool.getService(DebuggerTargetService.class);
+      if(traces==null||targets==null)continue;
+      for(var trace:traces.getOpenTraces()){
+        var target=targets.getTarget(trace);if(target!=null&&target.isValid())target.forceTerminateAsync().get(15,TimeUnit.SECONDS);
+      }
+    }
+    println("INSIGHT_DEBUGGER_STOPPED");
+  }
+}

package/references/native/InsightTraceInspect.java

@@ -0,0 +1,24 @@
+import com.google.gson.Gson;
+import db.DBHandle;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.data.OpenMode;
+import ghidra.framework.store.db.PackedDatabase;
+import ghidra.trace.database.DBTrace;
+import ghidra.util.task.TaskMonitor;
+import java.nio.file.Path;
+import java.util.*;
+
+/** Independent immutable readback of a packed trace, including its logical owner binding. */
+class InsightTraceInspect {
+  public static void main(String[] args){var output=System.out;System.setOut(System.err);try{
+    Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+    DBHandle db=PackedDatabase.getPackedDatabase(Path.of(args[0]).toFile(),true,TaskMonitor.DUMMY).open(TaskMonitor.DUMMY);
+    Object consumer=new Object();DBTrace trace=new DBTrace(db,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,consumer);
+    try{var options=trace.getOptions("Insight");
+      output.println(new Gson().toJson(Map.of("id",options.getString("Trace ID",""),"target",options.getString("Target",""),"context",options.getString("Context",""),
+        "name",trace.getName(),"modules",trace.getModuleManager().getAllModules().size(),"threads",trace.getThreadManager().getAllThreads().size())));
+    }finally{trace.release(consumer);}System.exit(0);
+  }catch(Throwable error){error.printStackTrace(System.err);output.println("{\"error\":\"trace_readback_failed\"}");System.exit(1);}}
+}