NetControl: allow reasons in remove_rule calls.

This adds the capability for the user to attach a reason when removing
or destroying a rule. The message will both be logged in netcontrol.log
and forwarded to the responsible plugins.

Addresses BIT-1655

scripts/base/frameworks/netcontrol/catch-and-release.bro

@@ -101,8 +101,10 @@ export {
 	##
 	## a: The address to be unblocked.
 	##
+	## reason: A reason for the unblock
+	##
 	## Returns: True if the address was unblocked.
-	global unblock_address_catch_release: function(a: addr) : bool;
+	global unblock_address_catch_release: function(a: addr, reason: string &default="") : bool;
 
 	## This function can be called to notify the cach and release script that activity by
 	## an IP address was seen. If the respective IP address is currently monitored by catch and
@@ -154,7 +156,7 @@ export {
 	global catch_release_block_new: event(a: addr, b: BlockInfo);
 	global catch_release_block_delete: event(a: addr);
 	global catch_release_add: event(a: addr, location: string);
-	global catch_release_delete: event(a: addr);
+	global catch_release_delete: event(a: addr, reason: string);
 	global catch_release_encountered: event(a: addr);
 }
 
@@ -287,9 +289,9 @@ event catch_release_add(a: addr, location: string)
 	drop_address_catch_release(a, location);
 	}
 
-event catch_release_delete(a: addr)
+event catch_release_delete(a: addr, reason: string)
 	{
-	unblock_address_catch_release(a);
+	unblock_address_catch_release(a, reason);
 	}
 
 event catch_release_encountered(a: addr)
@@ -386,7 +388,7 @@ function drop_address_catch_release(a: addr, location: string &default=""): Bloc
 
 	}
 
-function unblock_address_catch_release(a: addr): bool
+function unblock_address_catch_release(a: addr, reason: string &default=""): bool
 	{
 	if ( a !in blocks )
 		return F;
@@ -394,16 +396,18 @@ function unblock_address_catch_release(a: addr): bool
 @if ( ! Cluster::is_enabled() || ( Cluster::is_enabled() && Cluster::local_node_type() == Cluster::MANAGER ) )
 	local bi = blocks[a];
 	local log = populate_log_record(a, bi, UNBLOCK);
+	if ( reason != "" )
+		log$message = reason;
 	Log::write(CATCH_RELEASE, log);
 	delete blocks[a];
 	if ( bi?$block_until && bi$block_until > network_time() && bi$current_block_id != "" )
-		remove_rule(bi$current_block_id);
+		remove_rule(bi$current_block_id, reason);
 @endif
 @if ( Cluster::is_enabled() && Cluster::local_node_type() == Cluster::MANAGER )
 	event NetControl::catch_release_block_delete(a);
 @endif
 @if ( Cluster::is_enabled() && Cluster::local_node_type() != Cluster::MANAGER )
-	event NetControl::catch_release_delete(a);
+	event NetControl::catch_release_delete(a, reason);
 @endif
 
 	return T;

scripts/base/frameworks/netcontrol/cluster.bro

@@ -10,10 +10,10 @@ export {
 	global cluster_netcontrol_add_rule: event(r: Rule);
 
 	## This is the event used to transport remove_rule calls to the manager.
-	global cluster_netcontrol_remove_rule: event(id: string);
+	global cluster_netcontrol_remove_rule: event(id: string, reason: string);
 
 	## This is the event used to transport delete_rule calls to the manager.
-	global cluster_netcontrol_delete_rule: event(id: string);
+	global cluster_netcontrol_delete_rule: event(id: string, reason: string);
 }
 
 ## Workers need ability to forward commands to manager.
@@ -56,32 +56,32 @@ function add_rule(r: Rule) : string
 		}
 	}
 
-function delete_rule(id: string) : bool
+function delete_rule(id: string, reason: string &default="") : bool
 	{
 	if ( Cluster::local_node_type() == Cluster::MANAGER )
-		return delete_rule_impl(id);
+		return delete_rule_impl(id, reason);
 	else
 		{
-		event NetControl::cluster_netcontrol_delete_rule(id);
+		event NetControl::cluster_netcontrol_delete_rule(id, reason);
 		return T; # well, we can't know here. So - just hope...
 		}
 	}
 
-function remove_rule(id: string) : bool
+function remove_rule(id: string, reason: string &default="") : bool
 	{
 	if ( Cluster::local_node_type() == Cluster::MANAGER )
-		return remove_rule_impl(id);
+		return remove_rule_impl(id, reason);
 	else
 		{
-		event NetControl::cluster_netcontrol_remove_rule(id);
+		event NetControl::cluster_netcontrol_remove_rule(id, reason);
 		return T; # well, we can't know here. So - just hope...
 		}
 	}
 
 @if ( Cluster::local_node_type() == Cluster::MANAGER )
-event NetControl::cluster_netcontrol_delete_rule(id: string)
+event NetControl::cluster_netcontrol_delete_rule(id: string, reason: string)
 	{
-	delete_rule_impl(id);
+	delete_rule_impl(id, reason);
 	}
 
 event NetControl::cluster_netcontrol_add_rule(r: Rule)
@@ -89,9 +89,9 @@ event NetControl::cluster_netcontrol_add_rule(r: Rule)
 	add_rule_impl(r);
 	}
 
-event NetControl::cluster_netcontrol_remove_rule(id: string)
+event NetControl::cluster_netcontrol_remove_rule(id: string, reason: string)
 	{
-	remove_rule_impl(id);
+	remove_rule_impl(id, reason);
 	}
 
 event rule_expire(r: Rule, p: PluginState) &priority=-5

scripts/base/frameworks/netcontrol/main.bro

@@ -124,12 +124,14 @@ export {
 	##
 	## id: The rule to remove, specified as the ID returned by :bro:see:`NetControl::add_rule`.
 	##
+	## reason: Optional string argument giving information on why the rule was removed.
+	##
 	## Returns: True if succesful, the relevant plugin indicated that it knew
 	##          how to handle the removal. Note that again "success" means the
 	##          plugin accepted the removal. They might still fail to put it
 	##          into effect, as that might happen asynchronously and thus go
 	##          wrong at that point.
-	global remove_rule: function(id: string) : bool;
+	global remove_rule: function(id: string, reason: string &default="") : bool;
 
 	## Deletes a rule without removing in from the backends to which it has been
 	## added before. This mean that no messages will be sent to the switches to which
@@ -138,9 +140,11 @@ export {
 	##
 	## id: The rule to delete, specified as the ID returned by :bro:see:`add_rule` .
 	##
+	## reason: Optional string argument giving information on why the rule was deleted.
+	##
 	## Returns: True if removal is successful, or sent to manager.
 	##          False if the rule could not be found.
-	global delete_rule: function(id: string) : bool;
+	global delete_rule: function(id: string, reason: string &default="") : bool;
 
 	## Searches all rules affecting a certain IP address.
 	##
@@ -820,38 +824,49 @@ function rule_cleanup(r: Rule)
 	event NetControl::rule_destroyed(r);
 	}
 
-function delete_rule_impl(id: string): bool
+function delete_rule_impl(id: string, reason: string): bool
 	{
 	if ( id !in rules )
+		{
+		Reporter::error(fmt("Rule %s does not exist in NetControl::delete_rule", id));
 		return F;
+		}
 
 	local rule = rules[id];
 
 	rule$_active_plugin_ids = set();
 
 	rule_cleanup(rule);
+	if ( reason != "" )
+		log_rule_no_plugin(rule, REMOVED, fmt("delete_rule: %s", reason));
+	else
+		log_rule_no_plugin(rule, REMOVED, "delete_rule");
+
 	return T;
 	}
 
-function remove_rule_plugin(r: Rule, p: PluginState): bool
+function remove_rule_plugin(r: Rule, p: PluginState, reason: string &default=""): bool
 	{
 	local success = T;
 
-	if ( ! p$plugin$remove_rule(p, r) )
+	if ( ! p$plugin$remove_rule(p, r, reason) )
 		{
 		# still continue and send to other plugins
-		log_rule_error(r, "remove failed", p);
+		if ( reason != "" )
+			log_rule_error(r, fmt("remove failed (original reason: %s)", reason), p);
+		else
+			log_rule_error(r, "remove failed", p);
 		success = F;
 		}
 		else
 		{
-		log_rule(r, "REMOVE", REQUESTED, p);
+		log_rule(r, "REMOVE", REQUESTED, p, reason);
 		}
 
 	return success;
 	}
 
-function remove_rule_impl(id: string) : bool
+function remove_rule_impl(id: string, reason: string) : bool
 	{
 	if ( id !in rules )
 		{
@@ -865,7 +880,7 @@ function remove_rule_impl(id: string) : bool
 	for ( plugin_id in r$_active_plugin_ids )
 		{
 		local p = plugin_ids[plugin_id];
-		success = remove_rule_plugin(r, p);
+		success = remove_rule_plugin(r, p, reason);
 		}
 
 	return success;

scripts/base/frameworks/netcontrol/non-cluster.bro

@@ -12,14 +12,14 @@ function add_rule(r: Rule) : string
 	return add_rule_impl(r);
 	}
 
-function delete_rule(id: string) : bool
+function delete_rule(id: string, reason: string &default="") : bool
 	{
-	return delete_rule_impl(id);
+	return delete_rule_impl(id, reason);
 	}
 
-function remove_rule(id: string) : bool
+function remove_rule(id: string, reason: string &default="") : bool
 	{
-	return remove_rule_impl(id);
+	return remove_rule_impl(id, reason);
 	}
 
 event rule_expire(r: Rule, p: PluginState) &priority=-5

scripts/base/frameworks/netcontrol/plugin.bro

@@ -68,13 +68,7 @@ export {
 		## ``id`` field will match that of the add_rule() call.  Generally,
 		## a plugin that accepts an add_rule() should also accept the
 		## remove_rule().
-		remove_rule: function(state: PluginState, r: Rule) : bool &optional;
-
-		## A transaction groups a number of operations. The plugin can add them internally
-		## and postpone putting them into effect until committed. This allows to build a
-		## configuration of multiple rules at once, including replaying a previous state.
-		transaction_begin: function(state: PluginState) &optional;
-		transaction_end: function(state: PluginState) &optional;
+		remove_rule: function(state: PluginState, r: Rule, reason: string) : bool &optional;
 	};
 
 	## Table for a plugin to store instance-specific configuration information.

scripts/base/frameworks/netcontrol/plugins/acld.bro

@@ -247,7 +247,7 @@ function acld_add_rule_fun(p: PluginState, r: Rule) : bool
 	return T;
 	}
 
-function acld_remove_rule_fun(p: PluginState, r: Rule) : bool
+function acld_remove_rule_fun(p: PluginState, r: Rule, reason: string) : bool
 	{
 	if ( ! acld_check_rule(p, r) )
 		return F;
@@ -258,6 +258,14 @@ function acld_remove_rule_fun(p: PluginState, r: Rule) : bool
 	else
 		return F;
 
+	if ( reason != "" )
+		{
+		if ( ar?$comment )
+			ar$comment = fmt("%s (%s)", reason, ar$comment);
+		else
+			ar$comment = reason;
+		}
+
 	Broker::send_event(p$acld_config$acld_topic, Broker::event_args(acld_remove_rule, p$acld_id, r, ar));
 	return T;
 	}

scripts/base/frameworks/netcontrol/plugins/broker.bro

@@ -46,7 +46,7 @@ export {
 	};
 
 	global broker_add_rule: event(id: count, r: Rule);
-	global broker_remove_rule: event(id: count, r: Rule);
+	global broker_remove_rule: event(id: count, r: Rule, reason: string);
 
 	global broker_rule_added: event(id: count, r: Rule, msg: string);
 	global broker_rule_removed: event(id: count, r: Rule, msg: string);
@@ -155,12 +155,12 @@ function broker_add_rule_fun(p: PluginState, r: Rule) : bool
 	return T;
 	}
 
-function broker_remove_rule_fun(p: PluginState, r: Rule) : bool
+function broker_remove_rule_fun(p: PluginState, r: Rule, reason: string) : bool
 	{
 	if ( ! broker_check_rule(p, r) )
 		return F;
 
-	Broker::send_event(p$broker_config$topic, Broker::event_args(broker_remove_rule, p$broker_id, r));
+	Broker::send_event(p$broker_config$topic, Broker::event_args(broker_remove_rule, p$broker_id, r, reason));
 	return T;
 	}
 

scripts/base/frameworks/netcontrol/plugins/debug.bro

@@ -55,34 +55,22 @@ function debug_add_rule(p: PluginState, r: Rule) : bool
 	return F;
 	}
 
-function debug_remove_rule(p: PluginState, r: Rule) : bool
+function debug_remove_rule(p: PluginState, r: Rule, reason: string) : bool
 	{
-	local s = fmt("remove_rule: %s", r);
+	local s = fmt("remove_rule (%s): %s", reason, r);
 	debug_log(p, s);
 
 	event NetControl::rule_removed(r, p);
 	return T;
 	}
 
-function debug_transaction_begin(p: PluginState)
-	{
-	debug_log(p, "transaction_begin");
-	}
-
-function debug_transaction_end(p: PluginState)
-	{
-	debug_log(p, "transaction_end");
-	}
-
 global debug_plugin = Plugin(
 	$name=debug_name,
 	$can_expire = F,
 	$init = debug_init,
 	$done = debug_done,
 	$add_rule = debug_add_rule,
-	$remove_rule = debug_remove_rule,
-	$transaction_begin = debug_transaction_begin,
-	$transaction_end = debug_transaction_end
+	$remove_rule = debug_remove_rule
 	);
 
 function create_debug(do_something: bool) : PluginState

scripts/base/frameworks/netcontrol/plugins/openflow.bro

@@ -324,7 +324,7 @@ function openflow_add_rule(p: PluginState, r: Rule) : bool
 	return T;
 	}
 
-function openflow_remove_rule(p: PluginState, r: Rule) : bool
+function openflow_remove_rule(p: PluginState, r: Rule, reason: string) : bool
 	{
 	if ( ! openflow_check_rule(p, r) )
 		return F;
@@ -444,8 +444,6 @@ global openflow_plugin = Plugin(
 #	$done = openflow_done,
 	$add_rule = openflow_add_rule,
 	$remove_rule = openflow_remove_rule
-#	$transaction_begin = openflow_transaction_begin,
-#	$transaction_end = openflow_transaction_end
 	);
 
 function create_openflow(controller: OpenFlow::Controller, config: OfConfig &default=[]) : PluginState

scripts/base/frameworks/netcontrol/plugins/packetfilter.bro

@@ -63,7 +63,7 @@ function packetfilter_add_rule(p: PluginState, r: Rule) : bool
 	return F;
 	}
 
-function packetfilter_remove_rule(p: PluginState, r: Rule) : bool
+function packetfilter_remove_rule(p: PluginState, r: Rule, reason: string) : bool
 	{
 	if ( ! packetfilter_check_rule(r) )
 		return F;