Merge remote-tracking branch 'origin/topic/jsiwek/packet-analyzer-docs'

* origin/topic/jsiwek/packet-analyzer-docs:
  Fix a Sphinx warning about misformatted packet analyzer comment
  Add Zeekygen documentation support for packet analyzers

CHANGES

@@ -1,3 +1,10 @@
+3.3.0-dev.346 | 2020-09-24 16:03:28 -0700
+
+  * Fix a Sphinx warning about misformatted packet analyzer comment (Jon Siwek, Corelight)
+
+  * Add Zeekygen documentation support for packet analyzers (Jon Siwek, Corelight)
+
+  * Move packet_mgr to the zeek namespace (Tim Wojtulewicz, Corelight)
 
 3.3.0-dev.341 | 2020-09-24 08:16:45 -0700
 

VERSION

@@ -1 +1 @@
-3.3.0-dev.341
+3.3.0-dev.346

ci/update-zeekygen-docs.sh

@@ -59,6 +59,7 @@ generate_index "script_index" "autogenerated-script-index.rst"
 generate_index "package_index" "autogenerated-package-index.rst"
 generate_index "file_analyzer" "autogenerated-file-analyzer-index.rst"
 generate_index "proto_analyzer" "autogenerated-protocol-analyzer-index.rst"
+generate_index "packet_analyzer" "autogenerated-packet-analyzer-index.rst"
 
 echo
 

doc

@@ -1 +1 @@
-Subproject commit 912187484d674f08cb2e95f92e86cdcda5916e76
+Subproject commit 16f183e3d8f54db6f08130b6f5474192d3ada496

scripts/base/packet-protocols/null/main.zeek

@@ -11,14 +11,13 @@ redef PacketAnalyzer::ROOT::dispatch_map += {
 	[DLT_NULL] = PacketAnalyzer::DispatchEntry($analyzer=PacketAnalyzer::ANALYZER_NULL)
 };
 
+## From the Wireshark Wiki: AF_INET6ANALYZER, unfortunately, has different
+## values in {NetBSD,OpenBSD,BSD/OS}, {FreeBSD,DragonFlyBSD}, and
+## {Darwin/macOS}, so an IPv6 packet might have a link-layer header with 24, 28,
+## or 30 as the ``AF_`` value. As we may be reading traces captured on platforms
+## other than what we're running on, we accept them all here.
 redef dispatch_map += {
 	 [2] = PacketAnalyzer::DispatchEntry($analyzer=PacketAnalyzer::ANALYZER_IPV4),
-	
-	## From the Wireshark Wiki: AF_INET6ANALYZER, unfortunately, has different values in
-	## {NetBSD,OpenBSD,BSD/OS}, {FreeBSD,DragonFlyBSD}, and {Darwin/Mac OS X}, so an IPv6
-	## packet might have a link-layer header with 24, 28, or 30 as the AF_ value. As we
-	## may be reading traces captured on platforms other than what we're running on, we
-	## accept them all here.
 	[24] = PacketAnalyzer::DispatchEntry($analyzer=PacketAnalyzer::ANALYZER_IPV6),
 	[28] = PacketAnalyzer::DispatchEntry($analyzer=PacketAnalyzer::ANALYZER_IPV6),
 	[30] = PacketAnalyzer::DispatchEntry($analyzer=PacketAnalyzer::ANALYZER_IPV6)

src/zeekygen/Configuration.cc

@@ -21,6 +21,7 @@ static TargetFactory create_target_factory()
 	rval.Register<PackageTarget>("package");
 	rval.Register<ProtoAnalyzerTarget>("proto_analyzer");
 	rval.Register<FileAnalyzerTarget>("file_analyzer");
+	rval.Register<PacketAnalyzerTarget>("packet_analyzer");
 	rval.Register<ScriptSummaryTarget>("script_summary");
 	rval.Register<ScriptIndexTarget>("script_index");
 	rval.Register<ScriptTarget>("script");

src/zeekygen/Target.cc

@@ -12,6 +12,7 @@
 #include "analyzer/Manager.h"
 #include "analyzer/Component.h"
 #include "file_analysis/Manager.h"
+#include "packet_analysis/Manager.h"
 
 #include <sys/types.h>
 #include <sys/stat.h>
@@ -45,6 +46,17 @@ static void write_analyzer_component(FILE* f, const analyzer::Component* c)
 	fprintf(f, ":zeek:enum:`Analyzer::%s`\n\n", tag.c_str());
 	}
 
+static void write_analyzer_component(FILE* f, const packet_analysis::Component* c)
+	{
+	const auto& atag = packet_mgr->GetTagType();
+	string tag = util::fmt("ANALYZER_%s", c->CanonicalName().c_str());
+
+	if ( atag->Lookup("PacketAnalyzer", tag.c_str()) < 0 )
+		reporter->InternalError("missing packet analyzer tag for %s", tag.c_str());
+
+	fprintf(f, ":zeek:enum:`PacketAnalyzer::%s`\n\n", tag.c_str());
+	}
+
 static void write_analyzer_component(FILE* f, const file_analysis::Component* c)
 	{
 	const auto& atag = file_mgr->GetTagType();
@@ -78,6 +90,18 @@ static void write_plugin_components(FILE* f, const plugin::Plugin* p)
 			}
 			break;
 
+		case plugin::component::PACKET_ANALYZER:
+			{
+			const packet_analysis::Component* c =
+				dynamic_cast<const packet_analysis::Component*>(component);
+
+			if ( c )
+				write_analyzer_component(f, c);
+			else
+				reporter->InternalError("component type mismatch");
+			}
+			break;
+
 		case plugin::component::FILE_ANALYZER:
 			{
 			const auto* c =
@@ -285,6 +309,32 @@ void ProtoAnalyzerTarget::DoCreateAnalyzerDoc(FILE* f) const
 		}
 	}
 
+void PacketAnalyzerTarget::DoCreateAnalyzerDoc(FILE* f) const
+	{
+	fprintf(f, "Packet Analyzers\n");
+	fprintf(f, "================\n\n");
+
+	WriteAnalyzerTagDefn(f, "PacketAnalyzer");
+
+	plugin::Manager::plugin_list plugins = plugin_mgr->ActivePlugins();
+	plugin::Manager::plugin_list::const_iterator it;
+
+	for ( it = plugins.begin(); it != plugins.end(); ++it )
+		{
+		if ( ! ComponentsMatch(*it, plugin::component::PACKET_ANALYZER) )
+			continue;
+
+		write_plugin_section_heading(f, *it);
+		write_plugin_components(f, *it);
+		write_plugin_bif_items(f, *it, plugin::BifItem::CONSTANT,
+		                       "Options/Constants");
+		write_plugin_bif_items(f, *it, plugin::BifItem::GLOBAL, "Globals");
+		write_plugin_bif_items(f, *it, plugin::BifItem::TYPE, "Types");
+		write_plugin_bif_items(f, *it, plugin::BifItem::EVENT, "Events");
+		write_plugin_bif_items(f, *it, plugin::BifItem::FUNCTION, "Functions");
+		}
+	}
+
 void FileAnalyzerTarget::DoCreateAnalyzerDoc(FILE* f) const
 	{
 	fprintf(f, "File Analyzers\n");

src/zeekygen/Target.h

@@ -233,6 +233,26 @@ private:
 	void DoCreateAnalyzerDoc(FILE* f) const override;
 };
 
+/**
+ * Target to build packet analyzer documentation.
+ */
+class PacketAnalyzerTarget : public AnalyzerTarget {
+public:
+
+	/**
+	 * Ctor.
+	 * @param name Output file name.
+	 * @param pattern Dependency pattern.
+	 */
+	PacketAnalyzerTarget(const std::string& name, const std::string& pattern)
+		: AnalyzerTarget(name, pattern)
+		{ }
+
+private:
+
+	void DoCreateAnalyzerDoc(FILE* f) const override;
+};
+
 /**
  * Target to build package documentation.
  */