feat/text reporter

.gitignore

@@ -28,3 +28,5 @@ clickguard-*.tar
 
 # misc
 .DS_Store
+/clickguard
+/test/fixtures/*

lib/clickguard.ex

@@ -63,11 +63,8 @@ defmodule Clickguard do
   def run(path, opts \\ []) do
     {:ok, events} = parse(File.stream!(path), opts)
     {:ok, findings} = detect(events, opts)
-
-    {:ok,
-     Scorer.score(
-       findings,
-       actor_totals(events)
-     )}
+    {:ok, Scorer.score(findings, actor_totals(events))}
+  rescue
+    e in File.Error -> {:error, e.reason}
   end
 end

lib/clickguard/cli.ex

@@ -0,0 +1,26 @@
+defmodule Clickguard.CLI do
+  @moduledoc """
+  Handle the command line parsing and the dispatch to
+  `Clickguard.run/1` and `Clickguard.Reporter.Text` that
+  end up generating a formatted output.
+  """
+  alias Clickguard.Reporter.Text
+
+  def main(args) do
+    case OptionParser.parse(args, strict: []) do
+      {_flags, [input_file], _} ->
+        case Clickguard.run(input_file) do
+          {:ok, scores} ->
+            IO.write(Text.format(scores))
+
+          {:error, reason} ->
+            IO.puts(:stderr, "Error: " <> to_string(reason))
+            System.halt(1)
+        end
+
+      _ ->
+        IO.puts(:stderr, "Usage: clickguard input_log")
+        System.halt(1)
+    end
+  end
+end

lib/clickguard/detector.ex

@@ -5,8 +5,8 @@ defmodule Clickguard.Detector do
   Implementations:
 
     * `Clickguard.Detector.FreqIp` - IPs with >N requests per minute
-    * `Clickguard.Detector.Referer` - empty or suspicious referers (planned)
-    * `Clickguard.Detector.UserAgent` - match known datacenter/headless UAs (planned)
+    * `Clickguard.Detector.Referer` - empty or suspicious referers
+    * `Clickguard.Detector.UserAgent` - match known datacenter/headless UAs
 
   ## Implementing a detector
 

lib/clickguard/reporter.ex

@@ -0,0 +1,23 @@
+defmodule Clickguard.Reporter do
+  @moduledoc """
+  Behaviour for reporters.
+
+  Implementations:
+
+    * `Clickguard.Reporter.Text` - plain text without styling, best for text files and terminal output.
+
+  ## Implementing a reporter
+
+    defmodule MyReporter do
+      @behaviour Clickguard.Reporter
+
+      @impl true
+      def format(scores) do
+        # ...
+      end
+    end
+  """
+  alias Clickguard.Score
+
+  @callback format(scores :: [Score.t()]) :: iodata()
+end

lib/clickguard/reporter/text.ex

@@ -0,0 +1,63 @@
+defmodule Clickguard.Reporter.Text do
+  @moduledoc """
+  Generates plain text output from a list of `Clickguard.Score`.
+
+  Output is sorted by `band`, from the most severe to the least.
+  """
+  @behaviour Clickguard.Reporter
+
+  @severity_rank %{high: 0, medium: 1, low: 2}
+  @band_rank %{fraud: 0, suspect: 1, clear: 2}
+
+  @impl true
+  def format(scores) do
+    header = ["actor\tevents\tband\tscore\tsummary\tworst\n"]
+
+    rows =
+      scores
+      |> Enum.sort_by(fn s -> {Map.get(@band_rank, s.band), -s.score} end)
+      |> Enum.map(fn score ->
+        {actor_type, actor} = score.actor
+
+        [
+          to_string(actor_type),
+          ":",
+          actor,
+          "\t",
+          Integer.to_string(score.total_events),
+          "\t",
+          to_string(score.band),
+          "\t",
+          Integer.to_string(score.score),
+          "\t",
+          severity_summary(score.rule_summary),
+          "\t",
+          worst_rule(score.rule_summary),
+          "\n"
+        ]
+      end)
+
+    [header | rows]
+  end
+
+  defp severity_summary(rule_summary) do
+    rule_summary
+    |> Enum.frequencies_by(fn {_rule, {severity, _count}} -> severity end)
+    |> Enum.sort_by(fn {severity, _count} -> Map.get(@severity_rank, severity, 99) end)
+    |> Enum.map(fn {severity, count} ->
+      [to_string(severity), ": ", Integer.to_string(count)]
+    end)
+    |> Enum.intersperse(", ")
+  end
+
+  defp worst_rule(rule_summary) do
+    [{rule, {_severity, count}}] =
+      rule_summary
+      |> Enum.sort_by(fn {_rule, {severity, count}} ->
+        {Map.get(@severity_rank, severity, 99), -count}
+      end)
+      |> Enum.take(1)
+
+    [":", to_string(rule), " (", Integer.to_string(count), ")"]
+  end
+end

lib/clickguard/scorer.ex

@@ -9,14 +9,16 @@ defmodule Clickguard.Scorer do
   def score(findings, total_by_actor) do
     findings
     |> Enum.group_by(fn %Finding{subject: subj, actor_type: a_type} -> {a_type, subj} end)
-    |> Enum.map(fn {actor, findings} ->
-      summary = rule_summary(findings)
+    |> Enum.map(fn {actor, actor_findings} ->
+      summary = rule_summary(actor_findings)
       {band, score} = score_actor(summary)
       {_type, value} = actor
 
       %Score{
         actor: actor,
-        total_findings: length(findings),
+        total_findings: length(actor_findings),
+        # Keyed by IP string. Breaks when actor_type is :source or :session.
+        # Re-key total_by_actor by {actor_type, subject}.
         total_events: total_by_actor[value],
         rule_summary: summary,
         band: band,

mix.exs

@@ -8,6 +8,7 @@ defmodule Clickguard.MixProject do
       elixir: "~> 1.20",
       start_permanent: Mix.env() == :prod,
       deps: deps(),
+      escript: escript(),
       dialyzer: [
         plt_file: {:no_warn, "priv/plts/project.plt"},
         plt_add_apps: [:mix]
@@ -16,6 +17,10 @@ defmodule Clickguard.MixProject do
     ]
   end
 
+  defp escript do
+    [main_module: Clickguard.CLI]
+  end
+
   defp elixirc_paths(:test), do: ["lib", "test/support"]
   defp elixirc_paths(_), do: ["lib"]