Check for missing javadocs using checkstyle

Adds checkstyle:check within CircleCI building process that will check
for missing javadoc comments from public method. The configuration is
stored in checkstyle/*

.circleci/config.yml

@@ -11,6 +11,9 @@ jobs:
       - run:
           name: Spotless check
           command: bin/m spotless:check
+      - run:
+          name: Javadoc (checkstyle) check
+          command: bin/m checkstyle:check
       - run:
           name: Generate version.json
           command: bin/write_version_json.sh

checkstyle/checkstyle-suppressions.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE suppressions PUBLIC
+     "-//Checkstyle//DTD SuppressionFilter Configuration 1.0//EN"
+     "https://checkstyle.org/dtds/suppressions_1_0.dtd">
+
+<suppressions>
+  <suppress checks="InvalidJavadocPosition"
+             files="KinesisIO.java" />
+  <suppress checks="MissingJavadocMethod"
+             files="KinesisRecord.java" />
+  <suppress checks="JavadocParagraph"
+             files="ShardCheckpoint.java" />
+  <suppress checks="MissingJavadocMethod"
+             files="MemcachedStateInterface.java" />
+  <suppress checks="MissingJavadocMethod"
+             files="DatastoreStateInterface.java" />
+  <suppress checks="MissingJavadocMethod"
+             files="UserIdentity.java" />
+  <suppress checks="MissingJavadocMethod"
+             files="CloudtrailEvent.java" />
+</suppressions>

checkstyle/foxsec_checks.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+          "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+          "https://checkstyle.org/dtds/configuration_1_3.dtd">
+
+<!--
+    Checkstyle configuration specific to the foxsec-pipeline. This is lacking as we rely
+    heavily on spotless for the majority of linting.
+
+    Checkstyle is very configurable. Be sure to read the documentation at
+    http://checkstyle.org (or in your downloaded distribution).
+
+    To completely disable a check, just comment it out or delete it from the file.
+    To suppress certain violations please review suppression filters.
+ -->
+
+<module name = "Checker">
+    <property name="charset" value="UTF-8"/>
+
+    <property name="fileExtensions" value="java, properties, xml"/>
+    <!-- Excludes all 'module-info.java' files              -->
+    <!-- See https://checkstyle.org/config_filefilters.html -->
+    <module name="BeforeExecutionExclusionFileFilter">
+        <property name="fileNamePattern" value="module\-info\.java$"/>
+    </module>
+    <!-- https://checkstyle.org/config_filters.html#SuppressionFilter -->
+    <module name="SuppressionFilter">
+        <property name="file" value="${org.checkstyle.google.suppressionfilter.config}"
+                default="checkstyle/checkstyle-suppressions.xml" />
+        <property name="optional" value="true"/>
+    </module>
+
+    <module name="TreeWalker">
+        <module name="InvalidJavadocPosition"/>
+        <module name="JavadocTagContinuationIndentation"/>
+        <module name="JavadocParagraph"/>
+        <module name="JavadocMethod">
+            <property name="scope" value="public"/>
+            <property name="allowMissingParamTags" value="true"/>
+            <property name="allowMissingReturnTag" value="true"/>
+            <property name="allowedAnnotations" value="Override, Test, Setup, Teardown, ProcessElement, OnTimer, OnStale"/>
+            <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF"/>
+        </module>
+        <module name="MissingJavadocMethod">
+            <property name="scope" value="public"/>
+            <property name="minLineCount" value="2"/>
+            <property name="allowedAnnotations" value="Override, Test, Setup, Teardown, ProcessElement, OnTimer, OnStale"/>
+            <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF"/>
+        </module>
+    </module>
+</module>

pom.xml

@@ -78,6 +78,15 @@
                     </java>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+                <version>3.1.1</version>
+                <configuration>
+                    <logViolationsToConsole>true</logViolationsToConsole>
+                    <configLocation>checkstyle/foxsec_checks.xml</configLocation>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 

src/main/java/com/mozilla/secops/SourceCorrelation.java

@@ -218,6 +218,7 @@ public SourceCorrelator(HTTPRequestToggles toggles) {
       this.monitoredResource = toggles.getMonitoredResource();
     }
 
+    /** Transform documentation for users - see {@link DocumentingTransform} */
     public String getTransformDoc() {
       return String.format(
           "Source address alerting correlation, ISP analysis on minimum %d "

src/main/java/com/mozilla/secops/amo/AddonMatcher.java

@@ -45,6 +45,7 @@ public AddonMatcher(String monitoredResource, Integer suppressRecovery, String[]
     this.matchCriteria = matchCriteria;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return String.format(
         "Match abusive addon uploads using these patterns %s and generate alerts",

src/main/java/com/mozilla/secops/amo/AddonMultiIpLogin.java

@@ -69,6 +69,7 @@ public AddonMultiIpLogin(
     this.aggMatchers = aggMatchers;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return String.format(
         "Detect multiple account logins for the same account from different source addresses associated with different country codes. Alert on %s different countries and %s different IPs. Regex for account exceptions: %s",

src/main/java/com/mozilla/secops/amo/AddonMultiMatch.java

@@ -49,6 +49,7 @@ public AddonMultiMatch(String monitoredResource, Integer suppressRecovery, Integ
     this.matchAlertOn = matchAlertOn;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return String.format(
         "Detect distributed AMO submissions with the same file name. Alert on %s submissions of the same file name.",

src/main/java/com/mozilla/secops/amo/AddonMultiSubmit.java

@@ -48,6 +48,7 @@ public AddonMultiSubmit(
     this.matchAlertOn = matchAlertOn;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return String.format(
         "Detect distributed submissions based on file size intervals. Alert on %s submissions of the same rounded interval.",

src/main/java/com/mozilla/secops/amo/FxaAccountAbuseAlias.java

@@ -52,6 +52,7 @@ public FxaAccountAbuseAlias(
     this.maxAliases = maxAliases;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return String.format(
         "Alerts on aliased FxA accounts usage. A max of %s are allowed for one account in a given session.",

src/main/java/com/mozilla/secops/amo/FxaAccountAbuseNewVersion.java

@@ -56,6 +56,7 @@ public FxaAccountAbuseNewVersion(
     this.project = project;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return String.format(
         "Correlates AMO addon submissions with abusive FxA account creation alerts via iprepd. Also includes blacklisted accounts regex: %s",

src/main/java/com/mozilla/secops/amo/ReportRestriction.java

@@ -27,6 +27,7 @@ public ReportRestriction(String monitoredResource) {
     this.monitoredResource = monitoredResource;
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDoc() {
     return "Reports on request restrictions from AMO";
   }

src/main/java/com/mozilla/secops/authprofile/AuthProfile.java

@@ -340,6 +340,7 @@ public CritObjectAnalyze(AuthProfileOptions options) {
       useEventTimestampForAlert = options.getUseEventTimestampForAlert();
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return String.format(
           "Alert via %s immediately on auth events to specified objects: %s",
@@ -545,6 +546,7 @@ public StateAnalyze(AuthProfileOptions options) {
       useEventTimestampForAlert = options.getUseEventTimestampForAlert();
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return "Alert if an identity (can be thought of as a user) authenticates from a new IP";
     }

src/main/java/com/mozilla/secops/authstate/PruningStrategyEntryAge.java

@@ -23,6 +23,11 @@ public void setEntryAgePruningSeconds(long entryAgePruningSeconds) {
     this.entryAgePruningSeconds = entryAgePruningSeconds;
   }
 
+  /**
+   * Implementation of method of {@link PruningStrategyEntryAge}
+   *
+   * <p>See {@link PruningStrategy}
+   */
   public void pruneState(AuthStateModel s) {
     Map<String, AuthStateModel.ModelEntry> entries = s.getEntries();
 

src/main/java/com/mozilla/secops/authstate/PruningStrategyLatest.java

@@ -8,6 +8,11 @@
  * All entries are removed from the model with the exception of the entry with the latest timestamp.
  */
 public class PruningStrategyLatest implements PruningStrategy {
+  /**
+   * Implementation of method of {@link PruningStrategyLatest}
+   *
+   * <p>See {@link PruningStrategy}
+   */
   public void pruneState(AuthStateModel s) {
     ArrayList<AbstractMap.SimpleEntry<String, AuthStateModel.ModelEntry>> sorted =
         s.timeSortedEntries();

src/main/java/com/mozilla/secops/awsbehavior/AwsBehavior.java

@@ -79,6 +79,7 @@ public static class Matcher extends PTransform<PCollection<Event>, PCollection<A
 
     private Logger log;
 
+    /** Initialize new Matcher with a {@link CloudtrailMatcher} */
     public Matcher(CloudtrailMatcher cm) {
       this.cm = cm;
       log = LoggerFactory.getLogger(Matcher.class);
@@ -147,6 +148,7 @@ public static class Matchers extends PTransform<PCollection<Event>, PCollection<
     private CloudtrailMatcherManager cmmanager;
     private Logger log;
 
+    /** Initialize new Matchers with {@link AwsBehaviorOptions} */
     public Matchers(AwsBehaviorOptions options) throws IOException {
       log = LoggerFactory.getLogger(Matchers.class);
       cmmanagerPath = options.getCloudtrailMatcherManagerPath();

src/main/java/com/mozilla/secops/customs/Customs.java

@@ -103,6 +103,7 @@ public CustomsSummary(CustomsOptions options) {
       monitoredResource = options.getMonitoredResourceIndicator();
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return "Summarizes various event counts over 15 minute period.";
     }

src/main/java/com/mozilla/secops/customs/CustomsAccountCreation.java

@@ -45,6 +45,7 @@ public CustomsAccountCreation(CustomsOptions options) {
     this.escalate = options.getEscalateAccountCreation();
   }
 
+  /** Transform documentation for users - see {@link CustomsDocumentingTransform} */
   public String getTransformDocDescription() {
     return String.format(
         "Alert if single source address creates %d or more accounts within 10 minute"

src/main/java/com/mozilla/secops/customs/CustomsAccountCreationDist.java

@@ -43,6 +43,7 @@ public CustomsAccountCreationDist(CustomsOptions options) {
     this.escalate = options.getEscalateAccountCreationDistributed();
   }
 
+  /** Transform documentation for users - see {@link CustomsDocumentingTransform} */
   public String getTransformDocDescription() {
     return String.format(
         "Alert if at least %d accounts are created from different source addresses in a 10 "

src/main/java/com/mozilla/secops/customs/CustomsAlert.java

@@ -150,6 +150,12 @@ private static CustomsAlert baseAlert(Alert a) {
     return ret;
   }
 
+  /**
+   * Convert source login failure alert into a list of customs alerts.
+   *
+   * @param a Alert to convert
+   * @return ArrayList of CustomsAlert created
+   */
   public static ArrayList<CustomsAlert> convertSourceLoginFailure(Alert a) {
     ArrayList<CustomsAlert> ret = new ArrayList<>();
 
@@ -170,6 +176,12 @@ public static ArrayList<CustomsAlert> convertSourceLoginFailure(Alert a) {
     return ret;
   }
 
+  /**
+   * Convert a distributed source login failure alert into a list of customs alerts.
+   *
+   * @param a Alert to convert
+   * @return ArrayList of CustomsAlert created
+   */
   public static ArrayList<CustomsAlert> convertSourceLoginFailureDist(Alert a) {
     ArrayList<CustomsAlert> ret = new ArrayList<>();
 

src/main/java/com/mozilla/secops/customs/CustomsPasswordResetAbuse.java

@@ -30,6 +30,7 @@ public class CustomsPasswordResetAbuse
 
   private final Logger log = LoggerFactory.getLogger(CustomsAccountCreation.class);
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDocDescription() {
     return String.format(
         "Alert if single source requests password reset for at least %d distinct accounts "

src/main/java/com/mozilla/secops/customs/CustomsVelocity.java

@@ -45,6 +45,7 @@ public class CustomsVelocity extends PTransform<PCollection<Event>, PCollection<
   private final String maxmindCityDbPath;
   private final String maxmindIspDbPath;
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDocDescription() {
     return String.format(
         "Alert based on applying location velocity analysis to FxA events,"

src/main/java/com/mozilla/secops/customs/SourceLoginFailure.java

@@ -41,6 +41,7 @@ public SourceLoginFailure(Customs.CustomsOptions options) {
     escalate = options.getEscalateSourceLoginFailure();
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDocDescription() {
     return String.format(
         "Alert on %d login failures from a single source in a 10 minute window.", threshold);

src/main/java/com/mozilla/secops/customs/SourceLoginFailureDist.java

@@ -37,6 +37,7 @@ public SourceLoginFailureDist(Customs.CustomsOptions options) {
     escalate = options.getEscalateSourceLoginFailureDistributed();
   }
 
+  /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
   public String getTransformDocDescription() {
     return String.format(
         "Alert on login failures for a particular account from %d different source addresses "

src/main/java/com/mozilla/secops/gatekeeper/ETDTransforms.java

@@ -133,6 +133,7 @@ public GenerateETDAlerts(Options opts) {
       }
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return "Alerts are generated based on events sent from GCP's Event Threat Detection.";
     }

src/main/java/com/mozilla/secops/gatekeeper/GuardDutyTransforms.java

@@ -145,6 +145,7 @@ public GenerateGDAlerts(Options opts) {
       }
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return "Alerts are generated based on events sent from AWS's Guardduty.";
     }

src/main/java/com/mozilla/secops/httprequest/HTTPRequest.java

@@ -195,6 +195,7 @@ public ErrorRateAnalysis(
       log = LoggerFactory.getLogger(ErrorRateAnalysis.class);
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return String.format(
           "Alert if a single source address generates more than %d 4xx errors in a "
@@ -305,6 +306,7 @@ public HardLimitAnalysis(
       log = LoggerFactory.getLogger(HardLimitAnalysis.class);
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return String.format(
           "Alert if single source address makes more than %d requests in a 1 minute window.",
@@ -425,6 +427,7 @@ public UserAgentBlacklistAnalysis(
       log = LoggerFactory.getLogger(UserAgentBlacklistAnalysis.class);
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return new String(
           "Alert if client makes request with user agent that matches entry in blacklist.");
@@ -613,6 +616,7 @@ public EndpointAbuseAnalysis(
       }
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       String buf = null;
       for (int i = 0; i < endpoints.length; i++) {
@@ -845,6 +849,7 @@ public ThresholdAnalysis(
       log = LoggerFactory.getLogger(ThresholdAnalysis.class);
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       return String.format(
           "Alert if a single source address makes more than %.2f times the calculated"
@@ -1009,6 +1014,7 @@ public static class EndpointSequenceAbuseTimingInfo implements Serializable {
       public String secondMethod;
       public String secondPath;
 
+      /** Convert configuration to String */
       public String toString() {
         return String.format(
             "%d:%s:%s:%d:%s:%s",
@@ -1055,6 +1061,7 @@ public EndpointSequenceAbuse(
       }
     }
 
+    /** Transform documentation for users - see {@link com.mozilla.secops.DocumentingTransform} */
     public String getTransformDoc() {
       String buf = null;
       for (int i = 0; i < endpointPatterns.length; i++) {

src/main/java/com/mozilla/secops/metrics/CfgTickBuilder.java

@@ -35,7 +35,7 @@ private void mergeData(HashMap<String, String> in) {
   /**
    * Add documentation about a transform to the configuration tick
    *
-   * @param t {@link DocumentingTransform}
+   * @param t {@link com.mozilla.secops.DocumentingTransform}
    */
   public void withTransformDoc(DocumentingTransform t) {
     cfgData.put(String.format("heuristic_%s", t.getClass().getSimpleName()), t.getTransformDoc());

src/main/java/com/mozilla/secops/parser/FxaAuth.java

@@ -309,6 +309,11 @@ private Boolean discernPasswordForgotSendCode() {
     return false;
   }
 
+  /**
+   * Check if the auth event contained a successful certifcate signing
+   *
+   * @return Boolean
+   */
   public Boolean discernCertificateSignSuccess() {
     if (!(fxaAuthData.getPath().equals("/v1/certificate/sign"))) {
       return false;