@eyeauras/insight-cli 0.3.1 → 0.4.0

package/references/native/InsightInlineExecutor.java

@@ -0,0 +1,143 @@
+package insight;
+
+import com.google.gson.*;
+import generic.jar.ResourceFile;
+import ghidra.app.script.*;
+import ghidra.util.task.TaskMonitor;
+import java.io.*;
+import java.lang.reflect.*;
+import java.net.*;
+import java.nio.charset.StandardCharsets;
+import java.nio.channels.FileChannel;
+import java.nio.file.*;
+import java.security.MessageDigest;
+import java.util.*;
+import java.util.regex.*;
+import javax.tools.*;
+
+/** Owned Java-only inline executor. Never infers non-execution from exception text or stdout. */
+public final class InsightInlineExecutor {
+    static final int OUTPUT_BYTES=32768, MAX_DIAGNOSTICS=100;
+    static final Gson JSON=new GsonBuilder().serializeNulls().create();
+    static final class BoundedOutput extends OutputStream {
+        final ByteArrayOutputStream bytes=new ByteArrayOutputStream(); boolean truncated;
+        public synchronized void write(int b){if(bytes.size()<OUTPUT_BYTES)bytes.write(b);else truncated=true;}
+        public synchronized void write(byte[] b,int start,int length){int n=Math.min(length,OUTPUT_BYTES-bytes.size());bytes.write(b,start,n);if(n<length)truncated=true;}
+        synchronized String text(){return bytes.toString(StandardCharsets.UTF_8);}
+        synchronized Map<String,Object> value(){return Map.of("text",text(),"truncated",truncated,"maximumBytes",OUTPUT_BYTES);}
+    }
+    record Source(String name,String text,int prefixLines,int userLines,boolean wrapped) {}
+    /** Keep offsets/newlines, but hide comments and literals from declaration/import recognition. */
+    static String lexical(String s){
+        char[] out=s.toCharArray();int state=0;
+        for(int i=0;i<s.length();i++){
+            char c=s.charAt(i),n=i+1<s.length()?s.charAt(i+1):0;
+            if(state==0){
+                if(c=='/'&&n=='/'){out[i]=out[++i]=' ';state=1;}
+                else if(c=='/'&&n=='*'){out[i]=out[++i]=' ';state=2;}
+                else if(c=='"'&&i+2<s.length()&&s.startsWith("\"\"\"",i)){out[i]=out[i+1]=out[i+2]=' ';i+=2;state=5;}
+                else if(c=='"'||c=='\''){out[i]=' ';state=c=='"'?3:4;}
+            }else{
+                if(c!='\n'&&c!='\r')out[i]=' ';
+                if(state==1&&c=='\n')state=0;
+                else if(state==2&&c=='*'&&n=='/'){out[++i]=' ';state=0;}
+                else if((state==3||state==4)&&c=='\\'&&i+1<s.length()){if(s.charAt(i+1)!='\n')out[++i]=' ';}
+                else if((state==3&&c=='"')||(state==4&&c=='\''))state=0;
+                else if(state==5&&s.startsWith("\"\"\"",i)){out[i]=out[i+1]=out[i+2]=' ';i+=2;state=0;}
+            }
+        }
+        return new String(out);
+    }
+    static Source source(String code,String attempt){
+        String lex=lexical(code);
+        Matcher type=Pattern.compile("\\bpublic\\s+(?:(?:abstract|final|strictfp|sealed|non-sealed)\\s+)*(?:class|interface|enum|record)\\s+([A-Za-z_$][\\w$]*)").matcher(lex);
+        if(type.find()){
+            Matcher pkg=Pattern.compile("\\bpackage\\s+([A-Za-z_$][\\w$]*(?:\\s*\\.\\s*[A-Za-z_$][\\w$]*)*)\\s*;").matcher(lex);
+            String prefix=pkg.find()?pkg.group(1).replaceAll("\\s","")+".":"";
+            return new Source(prefix+type.group(1),code,0,code.split("\n",-1).length,false);
+        }
+        StringBuilder imports=new StringBuilder("import ghidra.app.script.GhidraScript;\n");char[] body=code.toCharArray();int lines=1;
+        Matcher im=Pattern.compile("(?m)^\\h*import\\s+(?:static\\s+)?[\\w.$*]+\\s*;").matcher(lex);
+        while(im.find()){
+            imports.append(code,im.start(),im.end()).append('\n');lines++;
+            for(int i=im.start();i<im.end();i++)if(body[i]!='\n'&&body[i]!='\r')body[i]=' ';
+        }
+        String name="InsightUser_"+attempt.replace("-","");
+        return new Source(name,imports+"public class "+name+" extends GhidraScript {\npublic void run() throws Exception {\n"+new String(body)+"\n}\n}\n",lines+2,code.split("\n",-1).length,true);
+    }
+    static String sha(String s)throws Exception{return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(s.getBytes(StandardCharsets.UTF_8)));}
+    static Map<String,Object> execution(String stage,boolean mayRun,Object invoked){
+        Map<String,Object> m=new LinkedHashMap<>();m.put("stage",stage);m.put("userCode",mayRun?"may_have_started":"not_started");m.put("entrypointInvoked",invoked);return m;
+    }
+    static List<Map<String,Object>> diagnostics(List<Diagnostic<? extends JavaFileObject>> all,Source source){
+        List<Map<String,Object>> out=new ArrayList<>();
+        for(var d:all){
+            if(out.size()==MAX_DIAGNOSTICS)break;
+            Map<String,Object> v=new LinkedHashMap<>();v.put("severity",d.getKind().name().toLowerCase(Locale.ROOT));v.put("code",d.getCode());
+            String message=d.getMessage(Locale.ROOT);v.put("message",message.substring(0,Math.min(message.length(),512)));v.put("messageTruncated",message.length()>512);
+            v.put("line",d.getLineNumber()>0?d.getLineNumber():null);v.put("column",d.getColumnNumber()>0?d.getColumnNumber():null);
+            long userLine=d.getLineNumber()-source.prefixLines();v.put("sourceLine",userLine>0&&userLine<=source.userLines()?userLine:null);v.put("generatedWrapper",source.wrapped());out.add(v);
+        }
+        return out;
+    }
+    static void failure(Map<String,Object> out,String stage,Throwable error,String fallback){
+        out.put("success",false);
+        Throwable cause=error;
+        if(cause instanceof InvocationTargetException e&&e.getTargetException()!=null)cause=e.getTargetException();
+        String message=cause==null?fallback:cause.getClass().getSimpleName()+": "+Objects.toString(cause.getMessage(),"");
+        out.put("diagnostic",Map.of("kind",stage.equals("compile")?"java-compile":stage.equals("load")?"java-load":"java-"+stage,"message",message.substring(0,Math.min(message.length(),2048)),"messageTruncated",message.length()>2048));
+    }
+    public static void execute(Path requestFile,GhidraState state,TaskMonitor monitor)throws Exception {
+        JsonObject p=JsonParser.parseString(Files.readString(requestFile)).getAsJsonObject();
+        Path root=requestFile.toAbsolutePath().getParent();String code=p.get("code").getAsString(),attempt=p.get("attemptId").getAsString();
+        if(!sha(code).equals(p.get("sourceSha256").getAsString())||!attempt.matches("[a-f0-9-]{36}"))throw new IllegalArgumentException("Inline attempt binding differs");
+        Source source=source(code,attempt);BoundedOutput build=new BoundedOutput(),console=new BoundedOutput();
+        Map<String,Object> out=new LinkedHashMap<>();out.put("protocol","insight-inline-v1");out.put("attemptId",attempt);out.put("requestId",p.get("requestId").getAsString());out.put("sourceSha256",sha(code));out.put("success",false);
+        String stage="prepare";boolean mayRun=false;Object invoked=false;
+        PrintStream originalOut=System.out,originalErr=System.err;
+        PrintWriter scriptWriter=new PrintWriter(new OutputStreamWriter(console,StandardCharsets.UTF_8),true);
+        try {
+            JavaCompiler compiler=ToolProvider.getSystemJavaCompiler();if(compiler==null)throw new IllegalStateException("JDK Java compiler is unavailable");
+            Path file=root.resolve("source").resolve(source.name().replace('.','/')+".java"),classes=root.resolve("classes");
+            Files.createDirectories(file.getParent());Files.createDirectory(classes);Files.writeString(file,source.text(),StandardOpenOption.CREATE_NEW);
+            stage="compile";DiagnosticCollector<JavaFileObject> ds=new DiagnosticCollector<>();
+            try(StandardJavaFileManager manager=compiler.getStandardFileManager(ds,Locale.ROOT,StandardCharsets.UTF_8)){
+                // Compile only this immutable attempt. No source discovery or annotation/plugin execution.
+                List<String> options=List.of("-proc:none","-encoding","UTF-8","-classpath",System.getProperty("java.class.path"),"-sourcepath",root.resolve("source").toString(),"-d",classes.toString());
+                boolean ok=Boolean.TRUE.equals(compiler.getTask(new OutputStreamWriter(build,StandardCharsets.UTF_8),manager,ds,options,null,manager.getJavaFileObjects(file)).call());
+                out.put("diagnostics",diagnostics(ds.getDiagnostics(),source));out.put("diagnosticsTruncated",ds.getDiagnostics().size()>MAX_DIAGNOSTICS);
+                if(!ok){
+                    PrintWriter messages=new PrintWriter(new OutputStreamWriter(build,StandardCharsets.UTF_8));
+                    for(var d:ds.getDiagnostics())messages.println("Inline.java:"+d.getLineNumber()+":"+d.getColumnNumber()+": "+d.getKind()+": "+d.getMessage(Locale.ROOT));messages.flush();
+                    failure(out,stage,null,ds.getDiagnostics().stream().filter(d->d.getKind()==Diagnostic.Kind.ERROR).findFirst().map(d->d.getMessage(Locale.ROOT)).orElse("Java compilation failed"));return;
+                }
+            }
+            stage="load";
+            try(URLClassLoader loader=new URLClassLoader(new URL[]{classes.toUri().toURL()},InsightInlineExecutor.class.getClassLoader())){
+                // Resolution and reflection are performed without class initialization.
+                Class<?> type=Class.forName(source.name(),false,loader);
+                if(type.getClassLoader()!=loader)throw new IllegalArgumentException("Source class collides with a parent class");
+                if(!GhidraScript.class.isAssignableFrom(type)||Modifier.isAbstract(type.getModifiers())||!Modifier.isPublic(type.getModifiers()))throw new IllegalArgumentException("Inline class must be a public concrete GhidraScript");
+                Constructor<?> constructor=type.getDeclaredConstructor();if(!Modifier.isPublic(constructor.getModifiers()))throw new IllegalAccessException("Inline class needs a public default constructor");
+                // Set the conservative barrier BEFORE initialization or any caller-controlled method.
+                System.setOut(new PrintStream(console,true,StandardCharsets.UTF_8));System.setErr(System.out);
+                stage="initialize";mayRun=true;Class.forName(source.name(),true,loader);
+                stage="construct";
+                GhidraScript script=(GhidraScript)constructor.newInstance();
+                script.setSourceFile(new ResourceFile(file.toFile()));
+                String args=p.get("args").getAsString().trim();script.setScriptArgs(args.isEmpty()?new String[0]:args.split("\\s+"));
+                stage="execute";invoked=null; // Framework setup may fail before run(); never assert run() entry from an exception.
+                script.execute(state,monitor,scriptWriter);
+                out.put("success",true);
+            }
+        }catch(Throwable error){failure(out,stage,error,"Inline attempt failed");}
+        finally {
+            scriptWriter.flush();
+            System.setOut(originalOut);System.setErr(originalErr);
+            out.put("execution",execution(stage,mayRun,invoked));out.put("compilerOutput",build.value());out.put("console_output",console.text());out.put("outputTruncated",console.truncated);
+            Path receipt=root.resolve("receipt.json"),temporary=root.resolve("receipt.new");Files.writeString(temporary,JSON.toJson(out),StandardOpenOption.CREATE_NEW);
+            try(FileChannel channel=FileChannel.open(temporary,StandardOpenOption.WRITE)){channel.force(true);}
+            Files.move(temporary,receipt,StandardCopyOption.ATOMIC_MOVE);
+        }
+    }
+}

package/references/native/InsightInlineScript.java

@@ -0,0 +1,14 @@
+import ghidra.app.script.GhidraScript;
+import insight.InsightInlineExecutor;
+import java.nio.file.Path;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+/** Only fixed trusted code is passed to the upstream script provider. User source is an input file. */
+public class InsightInlineScript extends GhidraScript {
+    public void run() throws Exception {
+        Path request=Path.of(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8));
+        InsightInlineExecutor.execute(request,getState(),monitor);
+        println("INSIGHT_INLINE_COMPLETE");
+    }
+}

package/references/native/InsightPeRanges.java

@@ -0,0 +1,92 @@
+package com.eyeauras.insight;
+
+import java.math.BigInteger;
+import java.util.*;
+import java.util.function.LongSupplier;
+
+/** Current mapped PE32+/AMD64 runtime regions, never semantic function reconstruction. */
+public final class InsightPeRanges {
+  public record Span(BigInteger begin,BigInteger endExclusive,boolean execute) {}
+  public interface Bytes { int read(BigInteger at,byte[] out)throws Exception; }
+  public record Range(BigInteger begin,BigInteger endExclusive,BigInteger recordAddress) {
+    public Map<String,Object> facts(){return Map.of("source","pe-exception-directory","begin",begin.toString(16),"endExclusive",endExclusive.toString(16),"tableRecordAddress",recordAddress.toString(16),"semanticMembership","not-established","instructionBoundary","not-checked","unwindInfo","not-parsed");}
+  }
+  public record Result(Map<String,Object> lookup,List<Range> ranges) {}
+  private static final BigInteger U64=BigInteger.ONE.shiftLeft(64);
+  private final List<BigInteger> addresses;
+  private final BigInteger base;private final List<Span> spans;private final Bytes memory;private final LongSupplier clock;private final int maximum;private final long start;
+  private int bytesRead=0,recordsValidated=0;private long recordCount=0;
+  private static final class Stop extends Exception {final String state,reason;Stop(String s,String r){state=s;reason=r;}}
+  public InsightPeRanges(BigInteger base,List<Span> spans,Bytes memory,int maximum,LongSupplier clock,List<BigInteger> addresses){
+    this(base,spans,memory,maximum,clock,addresses,clock.getAsLong());
+  }
+  public InsightPeRanges(BigInteger base,List<Span> spans,Bytes memory,int maximum,LongSupplier clock,List<BigInteger> addresses,long started){
+    if(base.signum()<0||base.compareTo(U64)>=0||maximum<1||maximum>16777216)throw new IllegalArgumentException("Invalid PE lookup bounds");
+    if(addresses.size()>20)throw new IllegalArgumentException("At most 20 addresses");this.addresses=List.copyOf(addresses);
+    start=started;this.base=base;this.spans=spans.stream().sorted(Comparator.comparing(Span::begin)).toList();this.memory=memory;this.maximum=maximum;this.clock=clock;
+  }
+  private void tick()throws Stop {if(clock.getAsLong()-start>=5_000_000_000L)throw new Stop("incomplete","timeout");}
+  private boolean mapped(BigInteger at,long length,boolean execute)throws Stop {
+    BigInteger end=at.add(BigInteger.valueOf(length));if(length<1||at.signum()<0||end.compareTo(U64)>0)return false;
+    BigInteger cursor=at;
+    for(Span s:spans){tick();if(s.endExclusive.compareTo(cursor)<=0)continue;if(s.begin.compareTo(cursor)>0)return false;if(execute&&!s.execute)return false;cursor=s.endExclusive.min(end);if(cursor.equals(end))return true;}
+    return false;
+  }
+  private byte[] read(BigInteger at,int length,String missing)throws Exception {
+    tick();if(length>maximum-bytesRead)throw new Stop("incomplete","byte_limit");
+    if(!mapped(at,length,false))throw new Stop("unavailable",missing);
+    byte[] out=new byte[length];int got;
+    try{got=memory.read(at,out);}catch(Exception e){throw new Stop("unavailable","memory_read_failed");}
+    // A failed/short read never establishes absence. Charge every reported physical byte.
+    if(got<0||got>length)throw new IllegalStateException("Invalid native byte count");bytesRead+=got;
+    if(got!=length)throw new Stop("unavailable","short_read");tick();return out;
+  }
+  private static int u16(byte[] a,int i){return (a[i]&255)|((a[i+1]&255)<<8);}
+  private static long u32(byte[] a,int i){return Integer.toUnsignedLong((a[i]&255)|((a[i+1]&255)<<8)|((a[i+2]&255)<<16)|((a[i+3]&255)<<24));}
+  private void valid(boolean condition,String reason)throws Stop {if(!condition)throw new Stop("malformed",reason);}
+  private BigInteger rva(long offset,long size)throws Stop {valid(offset>0&&size>0&&offset+size<=0x1_0000_0000L,"invalid_rva");BigInteger at=base.add(BigInteger.valueOf(offset));valid(at.add(BigInteger.valueOf(size)).compareTo(U64)<=0,"address_overflow");return at;}
+  public Result run()throws Exception {
+    List<Range> ranges=new ArrayList<>();String state="validated",reason="validated";
+    try{
+      byte[] dos=read(base,64,"headers_not_mapped");valid(u16(dos,0)==0x5a4d,"invalid_dos_signature");long pe=u32(dos,60);valid(pe>=64,"invalid_pe_offset");
+      byte[] header=read(base.add(BigInteger.valueOf(pe)),24,"headers_not_mapped");valid(u32(header,0)==0x4550,"invalid_pe_signature");
+      if(u16(header,4)!=0x8664)throw new Stop("unavailable","unsupported_machine");
+      int optionalSize=u16(header,20);valid(optionalSize>=112,"short_optional_header");
+      byte[] optional=read(base.add(BigInteger.valueOf(pe+24)),112,"headers_not_mapped");
+      if(u16(optional,0)!=0x20b)throw new Stop("unavailable","unsupported_optional_header");
+      long imageSize=u32(optional,56),headerSize=u32(optional,60),directories=u32(optional,108);
+      valid(imageSize>0&&headerSize>=pe+24+optionalSize&&headerSize<=imageSize,"invalid_image_headers");
+      valid(directories<=(optionalSize-112)/8,"short_optional_header");
+      valid(base.add(BigInteger.valueOf(imageSize)).compareTo(U64)<=0,"address_overflow");
+      if(!mapped(base,pe+24+optionalSize,false))throw new Stop("unavailable","headers_not_mapped");
+      if(directories<4){state="absent";reason="no_exception_directory";}
+      else{
+        byte[] directory=read(base.add(BigInteger.valueOf(pe+24+136)),8,"headers_not_mapped");
+        long table=u32(directory,0),size=u32(directory,4);
+        if(table==0&&size==0){state="absent";reason="no_exception_directory";}
+        else{
+          valid(table>0&&size>0&&size%12==0&&table%4==0&&table+size<=imageSize,"invalid_exception_directory");
+          recordCount=size/12;BigInteger tableAt=rva(table,size);long previousEnd=0;
+          for(long offset=0;offset<size;){
+            tick();int length=(int)Math.min(4092,size-offset);byte[] chunk=read(tableAt.add(BigInteger.valueOf(offset)),length,"table_not_mapped");
+            for(int i=0;i<length;i+=12){
+              tick();long begin=u32(chunk,i),end=u32(chunk,i+4),unwind=u32(chunk,i+8);
+              valid(begin>0&&begin<end&&end<=imageSize,"invalid_runtime_range");
+              valid(begin>=previousEnd,"unordered_or_overlapping_ranges");
+              valid(unwind>0&&unwind<imageSize&&unwind%4==0,"invalid_unwind_rva");
+              BigInteger lo=rva(begin,end-begin);
+              if(!mapped(lo,end-begin,true))throw new Stop("unavailable","runtime_range_not_initialized_executable");
+              if(!mapped(rva(unwind,1),1,false))throw new Stop("unavailable","unwind_not_mapped");
+              BigInteger hi=base.add(BigInteger.valueOf(end));
+              if(addresses.stream().anyMatch(at->at.compareTo(lo)>=0&&at.compareTo(hi)<0))ranges.add(new Range(lo,hi,tableAt.add(BigInteger.valueOf(offset+i))));previousEnd=end;recordsValidated++;
+            }
+            offset+=length;
+          }
+        }
+      }
+      tick();
+    }catch(Stop e){state=e.state;reason=e.reason;ranges.clear();}
+    boolean complete=state.equals("validated")||state.equals("absent");
+    return new Result(Map.of("state",state,"complete",complete,"reason",reason,"headersSource","current-mapped-memory","recordCount",recordCount,"recordsValidated",recordsValidated,"bytesRead",bytesRead,"maximumBytes",maximum,"deadlineMilliseconds",5000),List.copyOf(ranges));
+  }
+}

package/references/native/InsightResearchQueries.java

@@ -111,6 +111,27 @@ public class InsightResearchQueries extends GhidraScript {
     candidates.add(map("address",currentProgram.getImageBase().toString(),"name","image_base","kind","image_base_candidate","confirmed",false,"provenance","program.image-base"));
     return map("entry_points",confirmed,"count",confirmed.size(),"candidates",candidates,"scan",scan(),"truncated",stopped,"semantics",map("kind","metadata","limitation","External-entry designation is Ghidra metadata, not proof of OS startup behavior; candidates are not confirmed entries."));
   }
+  Object navigation()throws Exception{
+    final int cap=128;int functions=0,oneByte=0,entryInstructions=0,instructions=0,references=0,data=0,strings=0;long bodyBytes=0;
+    var fs=currentProgram.getFunctionManager().getFunctions(true);
+    while(fs.hasNext()&&functions<cap){if(!visit())break;var f=fs.next();functions++;long size=f.getBody().getNumAddresses();bodyBytes+=size;if(size==1)oneByte++;if(currentProgram.getListing().getInstructionAt(f.getEntryPoint())!=null)entryInstructions++;}
+    boolean functionsComplete=!fs.hasNext();
+    var is=currentProgram.getListing().getInstructions(true);
+    while(is.hasNext()&&instructions<cap){if(!visit())break;is.next();instructions++;}boolean instructionsComplete=!is.hasNext();
+    var rs=currentProgram.getReferenceManager().getReferenceIterator(currentProgram.getMinAddress());
+    while(rs.hasNext()&&references<cap){if(!visit())break;rs.next();references++;}boolean referencesComplete=!rs.hasNext();
+    var ds=currentProgram.getListing().getDefinedData(true);
+    while(ds.hasNext()&&data<cap){if(!visit())break;var d=ds.next();data++;if(d.hasStringValue())strings++;}boolean dataComplete=!ds.hasNext();
+    boolean complete=functionsComplete&&instructionsComplete&&referencesComplete&&dataComplete;
+    String assessment=functions>0&&oneByte*5>=functions*4&&(functions-entryInstructions)*5>=functions*4?"sparse-metadata":functions==0&&instructions==0?"no-code-observed":"observed-metadata";
+    return map("functions",map("sampled",functions,"oneByteBodies",oneByte,"bodyBytes",bodyBytes,"entriesWithInstructions",entryInstructions,"complete",functionsComplete),
+      "instructions",map("sampled",instructions,"complete",instructionsComplete),"references",map("sampled",references,"complete",referencesComplete),
+      "definedData",map("sampled",data,"strings",strings,"complete",dataComplete),
+      "scan",map("visited",visited,"maximum",maxScan,"sampleLimitPerCategory",cap,"complete",complete,"reason",complete?"exhausted":stopped?"budget":"sample_limit"),
+      "assessment",assessment,"assessmentAlgorithm","one-byte-and-missing-entry-instruction-ratio-at-least-0.8-v1",
+      "recommendations",assessment.equals("sparse-metadata")||assessment.equals("no-code-observed")?List.of("Treat missing stored xrefs, strings and function containment as unknown. For known function entries try functions inspect --fields decompiled_code,callees; refresh stale/failed output with functions force-decompile --function <entry>.","For executable bytes without a function entry use functions decode. These reads do not repair Listing instructions or stored xrefs.","Find undefined literals with analysis search-byte-patterns and its next_address continuation; strings search visits defined data only.","Consider an explicit bounded analysis/disassembly Update only when needed; this diagnostic does not run analyzers."):List.of("Use observed metadata for navigation; verify individual bodies and references for the question under study."),
+      "coverage","At most 128 inputs per category, in address order, sharing max-scan and a five-second deadline. References are stored DB references; strings count only sampled defined data. Observations and heuristics do not prove analysis or semantic completeness.");
+  }
   Object strings(boolean search)throws Exception{
     List<Object> rows=new PagedRows();String needle=str(search?"search_term":"filter","");Pattern regex=search?safeRegex(needle):null;String encoding=str("encoding","");int min=number("min_length",search?4:0,0,65536);var iter=currentProgram.getListing().getDefinedData(true);
     while(iter.hasNext()){if(!visit())break;var d=iter.next();if(!d.hasStringValue())continue;if(d.getLength()>65536){stopped=true;break;}String value=Objects.toString(d.getValue(),"");if(value.length()>8192){stopped=true;break;}String enc=d.getDataType().getName().toLowerCase(Locale.ROOT).contains("unicode")?"unicode":"ascii";
@@ -203,7 +224,7 @@ public class InsightResearchQueries extends GhidraScript {
     if(consumed==input.length&&available<maximum&&reason.equals("byte_limit"))reason="executable_block_end";
     return map("address",start.toString(),"language",language,"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString(),"input_bytes",HexFormat.of().formatHex(input),"input_sha256",HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(input)),"maximum_bytes",maximum,"maximum_instructions",maxInstructions,"instructions",rows,"consumed_bytes",consumed,"stop_reason",reason,"truncated",List.of("byte_limit","instruction_limit","truncated_instruction","executable_block_end").contains(reason),"semantics","Linear pseudo instructions in the selected program context; direct targets are computed from bytes, not function membership or stored xrefs.");
   }
-  Object execute(String operation)throws Exception{return switch(operation){case "/research_view"->map("modification",Long.toString(currentProgram.getModificationNumber()),"language",currentProgram.getLanguageID().toString(),"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString());case "/decode_instructions"->decodeInstructions();case "/find_dead_code"->dead();case "/detect_crypto_constants"->bytes(true);case "/search_byte_patterns"->bytes(false);case "/get_valid_data_types"->types(true);case "/find_data_types"->types(false);case "/validate_data_type"->validateType();case "/validate_function_prototype"->validatePrototype();case "/get_entry_points"->entries();case "/list_globals"->globals();case "/list_strings"->strings(false);case "/search_strings"->strings(true);case "/search_instructions"->instructions();default->throw new IllegalArgumentException("Unknown native query");};}
+  Object execute(String operation)throws Exception{return switch(operation){case "/navigation_diagnostic"->navigation();case "/research_view"->map("modification",Long.toString(currentProgram.getModificationNumber()),"language",currentProgram.getLanguageID().toString(),"compiler",currentProgram.getCompilerSpec().getCompilerSpecID().toString());case "/decode_instructions"->decodeInstructions();case "/find_dead_code"->dead();case "/detect_crypto_constants"->bytes(true);case "/search_byte_patterns"->bytes(false);case "/get_valid_data_types"->types(true);case "/find_data_types"->types(false);case "/validate_data_type"->validateType();case "/validate_function_prototype"->validatePrototype();case "/get_entry_points"->entries();case "/list_globals"->globals();case "/list_strings"->strings(false);case "/search_strings"->strings(true);case "/search_instructions"->instructions();default->throw new IllegalArgumentException("Unknown native query");};}
   public void run()throws Exception{
     var request=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8)).getAsJsonObject();p=request.getAsJsonObject("parameters");maxScan=number("max_scan",100000,1,200000);limit=number("limit",100,1,1000);offset=number("offset",0,0,2000000);deadline=System.nanoTime()+number("timeout_seconds",5,1,30)*1000000000L;
     boundedMonitor=TimeoutTaskMonitor.timeoutIn(number("timeout_seconds",5,1,30),TimeUnit.SECONDS,monitor);

package/references/native/InsightResearchView.java

@@ -0,0 +1,69 @@
+package com.eyeauras.insight;
+
+import com.xebyte.core.*;
+import ghidra.program.model.listing.Program;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.address.Address;
+import java.math.BigInteger;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** Precompiled, authenticated bridge read. Does not open, analyze, transact or save programs. */
+public final class InsightResearchView {
+  private final ProgramProvider programs;
+  private final ThreadingStrategy threading;
+  public InsightResearchView(ProgramProvider programs,ThreadingStrategy threading){this.programs=programs;this.threading=threading;}
+  private Program openProgram(String path){
+    if(programs==null||path==null||!path.startsWith("/")||path.length()>4096)throw new IllegalArgumentException("An explicit open program path is required");
+    Program selected=null;
+    for(Program p:programs.getAllOpenPrograms())if(p!=null&&!p.isClosed()&&p.getDomainFile()!=null&&path.equals(p.getDomainFile().getPathname())){
+      if(selected!=null&&selected!=p)throw new IllegalStateException("Program path is ambiguous");selected=p;
+    }
+    if(selected==null)throw new IllegalArgumentException("Program is not open");return selected;
+  }
+  @McpTool(path="/insight/research-view/v1",method="GET",description="Read modification/language/compiler of an already open program",access=ToolAccess.READ_ONLY)
+  public Response view(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path)throws Exception {
+    return threading.executeRead(()->{
+      Program selected=openProgram(path);
+      return Response.ok(Map.of("protocol","insight-research-view-v1","modification",Long.toString(selected.getModificationNumber()),"language",selected.getLanguageID().toString(),"compiler",selected.getCompilerSpec().getCompilerSpecID().toString()));
+    });
+  }
+  private static Map<String,Object> miss(String reason){return Map.of("status","not_found","reason",reason);}
+  private static Map<String,Object> resolved(Function function,Address at,String kind){
+    Map<String,Object> row=new LinkedHashMap<>();row.put("status","resolved");row.put("entryPoint",Long.toUnsignedString(function.getEntryPoint().getOffset(),16));
+    row.put("kind",kind);row.put("recordedBodyContainsAddress",function.getBody().contains(at));
+    if(!kind.equals("recorded-containing"))row.put("distanceBytes",at.subtract(function.getEntryPoint()));return row;
+  }
+  @McpTool(path="/insight/function-entries/v1",method="GET",description="Resolve up to 20 addresses using recorded bodies or a bounded preceding-entry candidate; no inferred membership",access=ToolAccess.READ_ONLY)
+  public Response entries(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path,
+      @Param(value="addresses",source=ParamSource.QUERY,allowEmpty=false) String addresses,
+      @Param(value="max_entry_distance",source=ParamSource.QUERY,allowEmpty=false) int maximum)throws Exception {
+    if(maximum<1||maximum>65536||addresses==null||addresses.length()>339)throw new IllegalArgumentException("Expected 1–20 addresses and a distance of 1–65536 bytes");
+    String[] words=addresses.split(",",-1);if(words.length<1||words.length>20)throw new IllegalArgumentException("Expected 1–20 addresses");
+    for(String word:words)if(!word.matches("[a-f0-9]{1,16}"))throw new IllegalArgumentException("Expected canonical default-space hexadecimal addresses");
+    return threading.executeRead(()->{
+      Program program=openProgram(path);long modification=program.getModificationNumber();var functions=program.getFunctionManager();
+      var space=program.getAddressFactory().getDefaultAddressSpace();var memory=program.getMemory();Map<String,Object> items=new LinkedHashMap<>();
+      for(String word:words){
+        if(items.containsKey(word)||!new BigInteger(word,16).toString(16).equals(word))throw new IllegalArgumentException("Expected distinct canonical addresses");
+        if(new BigInteger(word,16).bitLength()>space.getSize()){items.put(word,miss("address_out_of_range"));continue;}
+        Address at=space.getAddress(Long.parseUnsignedLong(word,16));
+        Function function=functions.getFunctionAt(at);
+        if(function!=null){items.put(word,resolved(function,at,"exact-entry"));continue;}
+        function=functions.getFunctionContaining(at);
+        if(function!=null){items.put(word,resolved(function,at,"recorded-containing"));continue;}
+        var block=memory.getBlock(at);
+        if(block==null||!block.isInitialized()||!block.isExecute()){items.put(word,miss("address_not_in_initialized_executable_block"));continue;}
+        // Address-seeded indexed iterator; consume at most one previous entry, never a full-table scan.
+        var previous=functions.getFunctions(at,false);
+        if(!previous.hasNext()){items.put(word,miss("no_preceding_entry"));continue;}
+        function=previous.next();Address entry=function.getEntryPoint();
+        if(!entry.getAddressSpace().equals(space)||entry.compareTo(at)>=0||!block.contains(entry)){items.put(word,miss("entry_outside_block"));continue;}
+        if(new BigInteger(word,16).subtract(new BigInteger(Long.toUnsignedString(entry.getOffset(),16),16)).compareTo(BigInteger.valueOf(maximum))>0){items.put(word,miss("entry_distance_exceeded"));continue;}
+        items.put(word,resolved(function,at,"preceding-entry-candidate"));
+      }
+      if(modification!=program.getModificationNumber())throw new IllegalStateException("Program changed during function-entry lookup");
+      return Response.ok(Map.of("protocol","insight-function-entries-v1","modification",Long.toString(modification),"items",items));
+    });
+  }
+}

package/references/native/InsightStringAnchors.java

@@ -0,0 +1,49 @@
+package com.eyeauras.insight;
+
+import com.xebyte.core.*;
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import ghidra.program.model.listing.Program;
+import java.math.BigInteger;
+import java.util.*;
+
+/** Authenticated precompiled read of an already-open byte-addressed default space. */
+public final class InsightStringAnchors {
+  // Upstream Response.ok omits null map values. This protocol requires explicit nullable facts.
+  private static final Gson JSON=new GsonBuilder().disableHtmlEscaping().serializeNulls().create();
+  private final ProgramProvider programs;private final ThreadingStrategy threading;
+  public InsightStringAnchors(ProgramProvider programs,ThreadingStrategy threading){this.programs=programs;this.threading=threading;}
+  private static BigInteger address(String value){if(value==null||!value.matches("0|[1-9a-f][a-f0-9]{0,15}"))throw new IllegalArgumentException("Expected canonical default-space address");return new BigInteger(value,16);}
+  @McpTool(path="/insight/string-anchors/v1",method="GET",description="Bounded literal byte matches with separate NUL-delimited candidate context",access=ToolAccess.READ_ONLY)
+  public Response anchors(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path,
+      @Param(value="text",source=ParamSource.QUERY,allowEmpty=false) String text,
+      @Param(value="encodings",source=ParamSource.QUERY,allowEmpty=false) String encodings,
+      @Param(value="scan_from",source=ParamSource.QUERY,allowEmpty=false) String start,
+      @Param(value="scan_through",source=ParamSource.QUERY,allowEmpty=false) String end,
+      @Param(value="resume_address",source=ParamSource.QUERY,allowEmpty=false) String resume,
+      @Param(value="resume_encoding",source=ParamSource.QUERY,allowEmpty=false) String encoding,
+      @Param(value="max_string_bytes",source=ParamSource.QUERY,allowEmpty=false) int cap,
+      @Param(value="max_bytes",source=ParamSource.QUERY,allowEmpty=false) int bytes,
+      @Param(value="max_candidates",source=ParamSource.QUERY,allowEmpty=false) int candidates,
+      @Param(value="timeout_seconds",source=ParamSource.QUERY,allowEmpty=false) int seconds,
+      @Param(value="limit",source=ParamSource.QUERY,allowEmpty=false) int limit)throws Exception{
+    var config=new InsightAnchorScan.Config(text,Arrays.asList(encodings.split(",",-1)),address(start),address(end),address(resume),encoding,cap,bytes,candidates,seconds,limit);
+    return threading.executeRead(()->{
+      if(programs==null||path==null||!path.startsWith("/")||path.length()>4096)throw new IllegalArgumentException("Explicit open program path required");
+      Program program=null;for(Program p:programs.getAllOpenPrograms())if(p!=null&&!p.isClosed()&&p.getDomainFile()!=null&&path.equals(p.getDomainFile().getPathname())){if(program!=null&&program!=p)throw new IllegalStateException("Ambiguous program path");program=p;}
+      if(program==null)throw new IllegalArgumentException("Program is not open");
+      var space=program.getAddressFactory().getDefaultAddressSpace();if(space.getAddressableUnitSize()!=1)throw new IllegalArgumentException("Only byte-addressed default space is supported");
+      if(config.end().bitLength()>space.getSize())throw new IllegalArgumentException("Range outside default address space");
+      long modification=program.getModificationNumber();var memory=program.getMemory();List<InsightAnchorScan.Span> raw=new ArrayList<>();
+      for(var block:memory.getBlocks())if(block.isInitialized()&&block.getStart().getAddressSpace().equals(space)){
+        var lo=new BigInteger(Long.toUnsignedString(block.getStart().getOffset(),16),16).max(config.start());var hi=new BigInteger(Long.toUnsignedString(block.getEnd().getOffset(),16),16).min(config.end());
+        if(lo.compareTo(hi)<=0)raw.add(new InsightAnchorScan.Span(lo,hi));
+      }
+      raw.sort(Comparator.comparing(InsightAnchorScan.Span::start));List<InsightAnchorScan.Span> spans=new ArrayList<>();
+      for(var s:raw){if(!spans.isEmpty()&&s.start().equals(spans.getLast().end().add(BigInteger.ONE))){var previous=spans.removeLast();spans.add(new InsightAnchorScan.Span(previous.start(),s.end()));}else spans.add(s);}
+      Map<String,Object> value=new LinkedHashMap<>(new InsightAnchorScan(config,spans,(at,out)->memory.getBytes(space.getAddress(at.longValue()),out),System::nanoTime).run());
+      if(program.getModificationNumber()!=modification)throw new IllegalStateException("Program changed during string-anchor scan");
+      value.put("modification",Long.toString(modification));return Response.text(JSON.toJson(value));
+    });
+  }
+}

package/references/persistent-client.mjs

@@ -0,0 +1,125 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+export class InsightCommandError extends Error {
+    rpc;
+    constructor(rpc) {
+        super(rpc.message);
+        this.rpc = rpc;
+        this.name = 'InsightCommandError';
+    }
+}
+export class InsightTransportError extends Error {
+    dispatched;
+    constructor(message, dispatched) {
+        super(message);
+        this.dispatched = dispatched;
+        this.name = 'InsightTransportError';
+    }
+}
+/** A thin client of Factory's existing stream, with no reconnect or command replay. */
+export async function connectInsight(options) {
+    const child = spawn(options.executable, [...(options.arguments ?? []), '--json-rpc'], { cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    const maximum = 4 * 1024 ** 2, decoder = new StringDecoder('utf8');
+    let buffer = '', bytes = 0, sequence = 0, accepting = true, failed = false, ended = false;
+    let closePromise, tail = Promise.resolve();
+    const pending = new Map();
+    // Drain diagnostics without retaining arbitrary stderr, paths, tokens or unbounded output.
+    child.stderr.resume();
+    const fail = (message) => {
+        if (failed)
+            return;
+        failed = true;
+        accepting = false;
+        for (const p of pending.values())
+            p.reject(new InsightTransportError(message, true));
+        pending.clear();
+        child.stdin.destroy();
+        child.stdout.destroy();
+    };
+    child.on('error', () => fail('Persistent CLI process failed.'));
+    child.stdout.on('error', () => fail('Persistent CLI output was lost.'));
+    child.stderr.on('error', () => fail('Persistent CLI diagnostic stream was lost.'));
+    child.stdin.on('error', () => fail('Persistent CLI input was lost; inspect request/status before retrying a changing command.'));
+    const exited = new Promise((resolve, reject) => {
+        child.once('close', (code, signal) => {
+            ended = true;
+            if (code !== 0 || signal || pending.size || buffer.trim()) {
+                fail('Persistent CLI closed without a complete acknowledged response.');
+                reject(new InsightTransportError('Persistent CLI transport ended unexpectedly.', false));
+            }
+            else if (failed)
+                reject(new InsightTransportError('Persistent CLI transport failed.', false));
+            else
+                resolve();
+        });
+    });
+    void exited.catch(() => { });
+    child.stdout.on('data', (chunk) => {
+        if (failed)
+            return;
+        buffer += decoder.write(chunk);
+        bytes += chunk.length;
+        if (bytes > maximum) {
+            fail('Persistent CLI response exceeded the bounded transport limit.');
+            return;
+        }
+        for (;;) {
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            bytes = Buffer.byteLength(buffer);
+            if (!line.trim())
+                continue;
+            try {
+                const r = JSON.parse(line);
+                if (!r || r.jsonrpc !== '2.0' || typeof r.id !== 'number' || !pending.has(r.id) || Object.hasOwn(r, 'result') === Object.hasOwn(r, 'error'))
+                    throw Error();
+                const p = pending.get(r.id);
+                if (Object.hasOwn(r, 'error') && (!r.error || typeof r.error !== 'object' || typeof r.error.code !== 'number' || !Number.isInteger(r.error.code) || typeof r.error.message !== 'string'))
+                    throw Error();
+                pending.delete(r.id);
+                if (r.error)
+                    p.reject(new InsightCommandError(r.error));
+                else
+                    p.resolve(r.result);
+            }
+            catch {
+                fail('Persistent CLI returned a malformed or uncorrelated response.');
+                return;
+            }
+        }
+    });
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', () => reject(new InsightTransportError('Could not start persistent CLI.', false))); });
+    return {
+        execute(argv) {
+            if (!Array.isArray(argv) || argv.length > 512 || argv.some(x => typeof x !== 'string' || x.includes('\0')) || Buffer.byteLength(JSON.stringify(argv)) > 1024 ** 2)
+                return Promise.reject(new TypeError('argv must be a bounded array of strings without NUL.'));
+            if (!accepting || failed || ended)
+                return Promise.reject(new InsightTransportError('Persistent CLI connection is closed.', false));
+            const args = [...argv];
+            const request = tail.then(() => {
+                if (failed || ended)
+                    throw new InsightTransportError('Persistent CLI connection was lost before dispatch.', false);
+                const id = ++sequence;
+                return new Promise((resolve, reject) => {
+                    pending.set(id, { resolve, reject });
+                    try {
+                        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method: 'cli.execute', params: { argv: args } }) + '\n');
+                    }
+                    catch {
+                        fail('Persistent CLI input was lost; inspect request/status before retrying a changing command.');
+                    }
+                });
+            });
+            tail = request.catch(() => { });
+            return request;
+        },
+        close() {
+            accepting = false;
+            return closePromise ??= tail.then(async () => { if (!failed && !ended)
+                child.stdin.end(); await exited; });
+        }
+    };
+}

package/references/persistent.md

@@ -0,0 +1,50 @@
+# Persistent research calls
+
+For a sequence of CLI research calls, keep one `insight-cli --json-rpc` frontend alive in the
+agent's long-lived JavaScript runtime. The Factory owner and Ghidra processes have their own
+lifetime; retaining only the owner still makes a new frontend validate its installed build.
+
+The package exports a small stdio client, independent of the facade's eager imports:
+
+```js
+import {connectInsight, InsightCommandError, InsightTransportError}
+  from '@eyeauras/insight-cli/persistent';
+
+const cli = await connectInsight({executable: 'insight-cli', cwd: projectDirectory});
+const result = await cli.execute([
+  'ghidra', 'functions', 'inspect', '--session', session, '--target', target,
+  '--function', 'main', '--fields', 'entry_point', '--include-call-context', 'false'
+]);
+// Keep cli for subsequent calls in this investigation.
+```
+
+When package-name resolution is unavailable in the agent host, dynamically import the
+[`persistent-client.mjs`](persistent-client.mjs) beside this reference by its absolute file URL.
+It is generated from the same canonical package module. In a persistent REPL retain `cli` as a
+binding across tool invocations. A new Node process per query does not retain this connection.
+For an explicit installed bin, use `{executable: process.execPath, arguments: [installedBin], cwd}`.
+`env` optionally supplies the child environment. There is no shell or separate profile/config.
+Use existing `--profile` argv flags when selecting a profile explicitly.
+
+`execute(argv)` returns the CLI result unchanged, without a JSON-RPC envelope. Calls are queued
+in admission order. Native work can be long: await the original promise through the agent host's
+existing wait facility. This V1 client deliberately has no per-request timeout or automatic
+reconnect/retry. Factory permissions, command validation, IDs and native budgets remain authoritative.
+
+* `InsightCommandError.rpc` preserves the JSON-RPC error code, message and data, including typed
+  CLI error results. A command failure leaves a healthy connection usable for the next command.
+* `InsightTransportError.dispatched === true` means the request was handed to the stream and its
+  acknowledgment is unavailable; it does not prove execution. Changing commands require their
+  existing request-ID/status recovery. The client never resends them.
+* `dispatched === false` means this client did not send that request, including queued requests
+  after a transport failure. Reconnection is an explicit new connection, not an implicit replay.
+
+The client bounds each response line to four MiB, validates IDs and envelopes, and fails the
+connection on malformed, uncorrelated or oversized replies. It drains stderr without retaining
+arbitrary native diagnostics in memory. Read command-level diagnostics from their typed results
+and the existing profile diagnostic locations.
+
+Finish owned Ghidra contexts with the normal scoped commands, following the project's shared
+server policy. Then `await cli.close()` drains already admitted requests and ends this stdio
+connection. It does not issue `ipc-server stop`, close another agent's context or stop a server.
+Do not call close while expecting to admit more requests.

package/references/query-semantics.md

@@ -51,6 +51,18 @@ finding. Narrow the query or raise its budget within the declared bound. Oversiz
 also stop a scan rather than silently claiming complete coverage. Returned string values are
 bounded; check truncation fields.
 
+`strings list` and `strings search` visit **defined data**, not every possible literal in memory.
+The visited-input budget includes non-string data. Zero matches with an incomplete scan means
+the searched prefix contains no matches; it does not establish absence. Increasing `--offset`
+only skips matching rows from that same scan and cannot reach a later unscanned string. These
+scans have no continuation cursor. Increase `--max-scan` up to 200000 when that covers the
+needed data. A narrower text filter alone does not skip earlier visited data or reach beyond
+that bound; use an explicitly addressed memory search when the needed region is known.
+For undefined ASCII/UTF-16 literals, encode the expected bytes and use
+`analysis search-byte-patterns --pattern <hex> --max-bytes <bytes>`; that separate initialized-
+memory search exposes `--scan-from`/`next_address` continuation. Byte matches still need
+interpretation and do not define string data or prove a stored xref exists.
+
 Bounded string/instruction regex search supports literals, escapes, anchors, character classes
 and at most one `.*` wildcard. Branching/nested repetition and unsupported patterns are rejected.
 Use the literal `strings search --contains` convenience when no regex is needed.