Stop logging secrets with a detach command

neykov · neykov · commit e05a722cfa7b · 2026-04-10T14:11:17.000+03:00
- Add 'detach <pid>' subcommand that stops secrets logging without restarting the target process. Allows for a safe attach/detach/re-attach cycles. - Add 'attach <pid> [<secrets_file>]' as an explicit subcommand, consistent with detach a nd list. Retain bare '<pid> [<secrets_file>]' for backwards compatibility without documenting it. - Add integration tests covering the full attach/detach/re-attach lifecycle and CLI argum ent-error cases for the new subcommands. Fixes #26
diff --git a/src/main/java/name/neykov/secrets/agent/AgentMain.java b/src/main/java/name/neykov/secrets/agent/AgentMain.java
@@ -25,6 +25,9 @@
 public class AgentMain {
     private static final Logger log = Logger.getLogger(AgentMain.class.getName());
 
+    private static volatile Transformer activeTransformer = null;
+    private static volatile Instrumentation attachInstr = null;
+
     // Created in process working directory
     public static final String DEFAULT_SECRETS_FILE = "ssl-master-secrets.txt";
 
@@ -39,7 +42,11 @@ public static void premain(String agentArgs, Instrumentation inst) {
     public static void agentmain(String agentArgs, Instrumentation inst) {
         File jarFile = getJarFile();
         initClassPath(inst, jarFile);
-        attach(agentArgs, inst, jarFile);
+        if ("detach".equals(agentArgs)) {
+            detach(jarFile);
+        } else {
+            attach(agentArgs, inst, jarFile);
+        }
         reloadClasses(inst);
     }
 
@@ -144,14 +151,21 @@ private static void reloadClasses(Instrumentation inst) {
         }
     }
 
-    private static void attach(String agentArgs, Instrumentation inst, File jarFile) {
+    private static void attach(String secretsPath, Instrumentation inst, File jarFile) {
+        if (activeTransformer != null) {
+            log.warning("Already attached; ignoring attach request.");
+            return;
+        }
+
         openBaseModule(inst);
 
         // MasterSecretCallback is loaded in boot class loader
-        String canonicalSecretsPath = getCanonicalSecretsPath(agentArgs);
+        String canonicalSecretsPath = getCanonicalSecretsPath(secretsPath);
         MasterSecretCallback.setSecretsFileName(canonicalSecretsPath);
 
-        inst.addTransformer(new Transformer(), true);
+        activeTransformer = new Transformer();
+        attachInstr = inst;
+        inst.addTransformer(activeTransformer, true);
 
         logSecurityProviders();
 
@@ -163,6 +177,19 @@ private static void attach(String agentArgs, Instrumentation inst, File jarFile)
                         + ". ");
     }
 
+    private static void detach(File jarFile) {
+        if (activeTransformer == null) {
+            log.warning("Not attached; ignoring detach request.");
+            return;
+        }
+
+        attachInstr.removeTransformer(activeTransformer);
+        activeTransformer = null;
+        attachInstr = null;
+
+        log.info("Successfully detached agent " + jarFile + ". ");
+    }
+
     private static void logSecurityProviders() {
         Provider[] sslProviders = Security.getProviders("SSLContext.TLS");
         if (sslProviders == null || sslProviders.length == 0) {
diff --git a/src/main/java/name/neykov/secrets/cli/AgentAttach.java b/src/main/java/name/neykov/secrets/cli/AgentAttach.java
@@ -20,7 +20,10 @@ public static void main(String[] args) throws Exception {
 
         try {
             CliArguments cliArguments = CliArguments.parse(args);
-            handle(jarUrl, jarFile, cliArguments.listOrPid, cliArguments.secretsPath);
+            String listOrPid = "list".equals(cliArguments.action) ? "list" : cliArguments.pid;
+            String attachOptions =
+                    "detach".equals(cliArguments.action) ? "detach" : cliArguments.secretsPath;
+            handle(jarUrl, jarFile, listOrPid, attachOptions);
         } catch (IllegalArgumentException e) {
             help(jarFile, e.getMessage());
             System.exit(1);
@@ -35,10 +38,14 @@ public static void main(String[] args) throws Exception {
     private static void help(File jarFile, String message) {
         System.err.println(message + ".");
         System.out.println();
-        System.out.println("Usage: java -jar " + jarFile.getName() + " <pid> [<secrets_file>]");
+        System.out.println(
+                "Usage: java -jar " + jarFile.getName() + " attach <pid> [<secrets_file>]");
+        System.out.println("       java -jar " + jarFile.getName() + " detach <pid>");
         System.out.println("       java -jar " + jarFile.getName() + " list");
         System.out.println();
         System.out.println("Options:");
+        System.out.println("  * attach - start logging secrets for the given process");
+        System.out.println("  * detach - stop logging secrets for the given process");
         System.out.println("  * list - shows available Java processes to attach to");
         System.out.println("  * pid - the process ID to attach to (required)");
         System.out.println("  * secrets_file - file path to log the shared secrets to (optional);");
diff --git a/src/main/java/name/neykov/secrets/cli/AttachHelper.java b/src/main/java/name/neykov/secrets/cli/AttachHelper.java
@@ -30,8 +30,12 @@ public static void handle(String jarPath, String pid, String attachOptions)
             System.out.print(AttachHelper.list());
         } else {
             try {
-                AttachHelper.attach(pid, jarPath, attachOptions);
-                System.out.println("Successfully attached to process ID " + pid + ".");
+                AttachHelper.loadagent(pid, jarPath, attachOptions);
+                if ("detach".equals(attachOptions)) {
+                    System.out.println("Successfully detached from process ID " + pid + ".");
+                } else {
+                    System.out.println("Successfully attached to process ID " + pid + ".");
+                }
             } catch (IllegalStateException e) {
                 String msg =
                         e.getMessage() != null
@@ -42,7 +46,7 @@ public static void handle(String jarPath, String pid, String attachOptions)
         }
     }
 
-    private static void attach(String pid, String jarPath, String options) {
+    private static void loadagent(String pid, String jarPath, String options) {
         try {
             VirtualMachine vm = VirtualMachine.attach(pid);
             vm.loadAgent(jarPath, options);
diff --git a/src/main/java/name/neykov/secrets/cli/CliArguments.java b/src/main/java/name/neykov/secrets/cli/CliArguments.java
@@ -1,12 +1,15 @@
 package name.neykov.secrets.cli;
 
 class CliArguments {
-    final String listOrPid;
+    final String action;
+
+    final String pid;
 
     final String secretsPath;
 
-    CliArguments(String listOrPid, String secretsPath) {
-        this.listOrPid = listOrPid;
+    CliArguments(String action, String pid, String secretsPath) {
+        this.action = action;
+        this.pid = pid;
         this.secretsPath = secretsPath;
     }
 
@@ -18,7 +21,19 @@ static CliArguments parse(String[] args) {
             if (args.length > 1) {
                 throw new IllegalArgumentException("'list' action does not take any arguments");
             }
-            return new CliArguments("list", "");
+            return new CliArguments("list", null, "");
+        } else if ("detach".equals(args[0])) {
+            if (args.length != 2) {
+                throw new IllegalArgumentException(
+                        "'detach' action requires exactly one argument: the process ID");
+            }
+            return new CliArguments("detach", args[1], "");
+        } else if ("attach".equals(args[0])) {
+            if (args.length < 2 || args.length > 3) {
+                throw new IllegalArgumentException(
+                        "'attach' action requires a process ID and an optional secrets file path");
+            }
+            return new CliArguments("attach", args[1], args.length == 3 ? args[2] : "");
         } else {
             String pid = null;
             String secretPath = null;
@@ -44,7 +59,7 @@ static CliArguments parse(String[] args) {
                 secretPath = "";
             }
 
-            return new CliArguments(pid, secretPath);
+            return new CliArguments("attach", pid, secretPath);
         }
     }
 
@@ -59,7 +74,10 @@ public boolean equals(Object o) {
 
         CliArguments that = (CliArguments) o;
 
-        if (!listOrPid.equals(that.listOrPid)) {
+        if (!action.equals(that.action)) {
+            return false;
+        }
+        if (pid != null ? !pid.equals(that.pid) : that.pid != null) {
             return false;
         }
         return secretsPath.equals(that.secretsPath);
@@ -68,8 +86,11 @@ public boolean equals(Object o) {
     @Override
     public String toString() {
         return "CliArguments{"
-                + "listOrPid='"
-                + listOrPid
+                + "action='"
+                + action
+                + '\''
+                + ", pid='"
+                + pid
                 + '\''
                 + ", secretsPath='"
                 + secretsPath
diff --git a/src/test/docker/test.sh b/src/test/docker/test.sh
@@ -143,6 +143,34 @@ check_provider_logs() {
   fi
 }
 
+# Run a single client connection without pcap or key assertions.
+run_client() {
+  local proto="$1" cp="$2" provider="$3"
+  docker run --network ssl-secrets --rm \
+    -v $ROOT:/project -v $SECRETS_VOLUME:/secrets \
+    ssl-secrets-server java -cp "$cp" \
+    -Djavax.net.ssl.trustStoreType=jks \
+    -Djavax.net.ssl.trustStore=/secrets/truststore \
+    -Djavax.net.ssl.trustStorePassword=password \
+    -Djdk.tls.client.protocols=$proto \
+    -Dprovider=$provider \
+    name.neykov.secrets.TestClient https://ssl-secrets-server/secret.txt
+}
+
+assert_has_keys() {
+  local file="$1"
+  [ -s "$file" ] || { echo "Expected keys in $file but file is empty or absent" >&2; return 1; }
+}
+
+assert_no_keys() {
+  local file="$1"
+  if [ -s "$file" ]; then
+    echo "Expected no keys in $file but file contains:" >&2
+    cat "$file" >&2
+    return 1
+  fi
+}
+
 # Verify that a captured pcap can be decrypted using the given keylog file.
 check_decryptable() {
   local keyfile="$1"
@@ -385,3 +413,132 @@ run_ibm_jdk8_tests() {
 run_ibm_jdk8_tests
 
 docker rm -f ssl-secrets-server
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  Detach/re-attach test: attach → detach → re-attach lifecycle
+#  Verifies that secrets stop being logged after detach and resume after
+#  re-attach. Also exercises the double-attach and detach-without-attach guards.
+#  Run once on a stable LTS; the detach logic is JVM-version-independent.
+# ══════════════════════════════════════════════════════════════════════════════
+
+run_detach_test() {
+  local java_version="$1"
+
+  echo -e "\n" \
+    "=============================================\n" \
+    "   Detach/re-attach - Java $java_version \n" \
+    "=============================================\n\n"
+
+  docker rm -f $(docker ps -qa) 2>/dev/null || true
+  docker build -f $CWD/Dockerfile.server $CWD -t ssl-secrets-server \
+    --build-arg JAVA_IMAGE_TAG=$java_version
+
+  local cp="$DEFAULT_CP"
+  local provider="JSSE"
+  local proto="TLSv1.2"
+
+  # Start server without agent.
+  docker run -d --name ssl-secrets-server --network ssl-secrets \
+    -v $ROOT:/project \
+    -v $SECRETS_VOLUME:/secrets \
+    ssl-secrets-server java -cp "$cp" \
+    -Dprovider=$provider \
+    -Dkeystore.file=/secrets/keystore \
+    name.neykov.secrets.TestServer
+  wait_for_log ssl-secrets-server "server ready"
+
+  # ── Attach ───────────────────────────────────────────────────────────────
+  rm -f $SECRETS_VOLUME/server.keys
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH 1 /secrets/server.keys
+  check_provider_logs "$provider" "attach"
+
+  # ── 1. Secrets captured after attach ─────────────────────────────────────
+  run_client "$proto" "$cp" "$provider"
+  assert_has_keys $SECRETS_VOLUME/server.keys
+
+  # ── 2. Double-attach guard: second attach logs "Already attached" ─────────
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH 1 /secrets/server.keys
+  wait_for_log ssl-secrets-server "Already attached"
+
+  # ── 3. Detach: secrets NOT captured for subsequent connections ────────────
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH detach 1
+  wait_for_log ssl-secrets-server "Successfully detached agent"
+
+  rm -f $SECRETS_VOLUME/server.keys
+  run_client "$proto" "$cp" "$provider"
+  assert_no_keys $SECRETS_VOLUME/server.keys
+
+  # ── 4. Detach-without-attach guard: second detach logs "Not attached" ─────
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH detach 1
+  wait_for_log ssl-secrets-server "Not attached"
+
+  # ── 5. Re-attach: secrets captured again ─────────────────────────────────
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH 1 /secrets/server.keys
+  rm -f $SECRETS_VOLUME/server.keys
+  run_client "$proto" "$cp" "$provider"
+  assert_has_keys $SECRETS_VOLUME/server.keys
+}
+
+run_detach_test 21
+
+docker rm -f ssl-secrets-server
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  Premain-detach test: -javaagent load → runtime detach lifecycle
+#  Verifies that an agent loaded via -javaagent: can be detached at runtime.
+#  The Instrumentation object passed to premain is different from the one
+#  passed to agentmain; this exercises the cross-instance removeTransformer
+#  + retransformClasses path.
+# ══════════════════════════════════════════════════════════════════════════════
+
+run_premain_detach_test() {
+  local java_version="$1"
+
+  echo -e "\n" \
+    "=============================================\n" \
+    "   Premain detach - Java $java_version \n" \
+    "=============================================\n\n"
+
+  docker rm -f $(docker ps -qa) 2>/dev/null || true
+  docker build -f $CWD/Dockerfile.server $CWD -t ssl-secrets-server \
+    --build-arg JAVA_IMAGE_TAG=$java_version
+
+  local cp="$DEFAULT_CP"
+  local provider="JSSE"
+  local proto="TLSv1.2"
+
+  # Start server with -javaagent (premain path).
+  rm -f $SECRETS_VOLUME/server.keys
+  docker run -d --name ssl-secrets-server --network ssl-secrets \
+    -v $ROOT:/project \
+    -v $SECRETS_VOLUME:/secrets \
+    ssl-secrets-server java -cp "$cp" \
+    -Dprovider=$provider \
+    -Dkeystore.file=/secrets/keystore \
+    -javaagent:/project/$JAR_PATH=/secrets/server.keys \
+    name.neykov.secrets.TestServer
+  wait_for_log ssl-secrets-server "server ready"
+  check_provider_logs "$provider" "agent"
+
+  # ── 1. Secrets captured with premain agent ────────────────────────────────
+  run_client "$proto" "$cp" "$provider"
+  assert_has_keys $SECRETS_VOLUME/server.keys
+
+  # ── 2. Runtime detach stops capture ──────────────────────────────────────
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH detach 1
+  wait_for_log ssl-secrets-server "Successfully detached agent"
+
+  rm -f $SECRETS_VOLUME/server.keys
+  run_client "$proto" "$cp" "$provider"
+  assert_no_keys $SECRETS_VOLUME/server.keys
+
+  # ── 3. Re-attach resumes capture ─────────────────────────────────────────
+  docker exec ssl-secrets-server java -jar /project/$JAR_PATH 1 /secrets/server.keys
+  rm -f $SECRETS_VOLUME/server.keys
+  run_client "$proto" "$cp" "$provider"
+  assert_has_keys $SECRETS_VOLUME/server.keys
+}
+
+run_premain_detach_test 21
+
+docker rm -f ssl-secrets-server
diff --git a/src/test/docker/test_errors.sh b/src/test/docker/test_errors.sh
@@ -52,3 +52,28 @@ OUT=$(docker run --rm --network none \
 
 [[ "$OUT" == *"Invalid JAVA_HOME environment variable"* ]] || exit 1
 [[ "$OUT" == *"Must point to a local JDK installation containing a 'lib/tools.jar'"* ]] || exit 1
+
+# 'detach' with no PID argument
+OUT=$(docker run --rm --network none \
+  -v $ROOT:/project \
+  azul/zulu-openjdk:8 \
+  java -jar /project/$JAR_PATH detach 2>&1)
+
+[[ "$OUT" == *"'detach' action requires exactly one argument"* ]] || exit 1
+[[ "$OUT" == *"Usage"* ]] || exit 1
+
+# 'detach' with extra argument
+OUT=$(docker run --rm --network none \
+  -v $ROOT:/project \
+  azul/zulu-openjdk:8 \
+  java -jar /project/$JAR_PATH detach 1234 extra 2>&1)
+
+[[ "$OUT" == *"'detach' action requires exactly one argument"* ]] || exit 1
+
+# 'detach' against a non-existent PID
+OUT=$(docker run --rm --network none \
+  -v $ROOT:/project \
+  azul/zulu-openjdk:8 \
+  java -jar /project/$JAR_PATH detach 99999 2>&1)
+
+[[ "$OUT" == *"Failed to attach to java process 99999"* ]] || exit 1
diff --git a/src/test/java/name/neykov/secrets/cli/TestCliArguments.java b/src/test/java/name/neykov/secrets/cli/TestCliArguments.java
