Noting JEP-210 impact on ConsoleNote encoding

core/src/main/java/hudson/console/ConsoleLogFilter.java

@@ -36,13 +36,19 @@
 import javax.annotation.Nonnull;
 import java.io.IOException;
 import java.io.OutputStream;
+import java.io.Serializable;
+import jenkins.util.JenkinsJVM;
 
 /**
  * A hook to allow filtering of information that is written to the console log.
  * Unlike {@link ConsoleAnnotator} and {@link ConsoleNote}, this class provides
  * direct access to the underlying {@link OutputStream} so it's possible to suppress
  * data, which isn't possible from the other interfaces.
  * ({@link ArgumentListBuilder#add(String, boolean)} is a simpler way to suppress a single password.)
+ * <p>Implementations which are {@link Serializable} may be sent to an agent JVM for processing.
+ * In particular, this happens under <a href="https://jenkins.io/jep/210">JEP-210</a>.
+ * In this case, the implementation should not assume that {@link JenkinsJVM#isJenkinsJVM},
+ * and if generating {@link ConsoleNote}s will need to encode them on the master side first.
  * @author dty
  * @since 1.383
  * @see BuildWrapper#decorateLogger

core/src/main/java/hudson/console/ConsoleNote.java

@@ -110,6 +110,17 @@
  * is also important, although {@link ConsoleNote}s that failed to deserialize will be simply ignored, so the
  * worst thing that can happen is that you just lose some notes.
  *
+ * <p>
+ * Note that {@link #encode}, {@link #encodeTo(OutputStream)}, and {@link #encodeTo(Writer)}
+ * should be called on the Jenkins master.
+ * If called from an agent JVM, a signature will be missing and so as per
+ * <a href="https://jenkins.io/security/advisory/2017-02-01/#persisted-cross-site-scripting-vulnerability-in-console-notes">SECURITY-382</a>
+ * the console note will be ignored.
+ * This may happen, in particular, if the note was generated by a {@link ConsoleLogFilter} sent to the agent.
+ * Alternative solutions include using a {@link ConsoleAnnotatorFactory} where practical;
+ * or generating the encoded form of the note on the master side and sending it to the agent,
+ * for example by saving that form as instance fields in a {@link ConsoleLogFilter} implementation.
+ *
  * <h2>Behaviour, JavaScript, and CSS</h2>
  * <p>
  * {@link ConsoleNote} can have associated {@code script.js} and {@code style.css} (put them