[GitHub] csantanapr closed pull request #3801: add a doc for securing actions

[GitBox <gi...@apache.org>]

csantanapr closed pull request #3801: add a doc for securing actions 
URL: https://github.com/apache/incubator-openwhisk/pull/3801
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/docs/actions.md b/docs/actions.md
index c7fbd99ba8..3a9867fc4f 100644
--- a/docs/actions.md
+++ b/docs/actions.md
@@ -19,23 +19,22 @@
 
 # Creating and invoking OpenWhisk actions
 
+Actions are stateless functions that run on the OpenWhisk platform. For example, an action can
+be used to detect the faces in an image, respond to a database change, respond to an API call,
+or post a Tweet. In general, an action is invoked in response to an event and produces some
+observable output.
 
-Actions are stateless code snippets that run on the OpenWhisk platform.
-For example, an action can be used to detect the faces in an image, respond to a database change,
-aggregate a set of API calls, or post a Tweet.
-An action can be written as a JavaScript, Swift, Python or PHP function, a Java method,
-any binary-compatible executable including Go programs and custom executables packaged as Docker containers.
+An action may be created from a function programmed using a number of supported languages, or
+from a binary-compatible executable, or even executables packaged as Docker containers.
 
-Actions can be explicitly invoked, or run in response to an event.
-In either case, each run of an action results in an activation record that is identified by a unique activation ID.
-The input to an action and the result of an action are a dictionary of key-value pairs, where the key is a string and the value a valid JSON value.
-Actions can also be composed of calls to other actions or a defined sequence of actions.
+_Prerequisite:_ The OpenWhisk CLI [`wsk`](https://github.com/apache/incubator-openwhisk-cli/releases)
+makes it easy to create and invoke actions. Instructions for configuring the CLI are available [here](???).
 
-## Prerequisites
-
-You will need to use OpenWhisk CLI. Read how to use it when running OpenWhisk from a VM [here](https://github.com/apache/incubator-openwhisk/blob/master/tools/vagrant/README.md#using-cli-from-outside-the-vm). Or download binaries for your platform [here](https://github.com/apache/incubator-openwhisk-cli/releases). You can also download the CLI directly from your local installation at the _https://<IP_ADDRESS>/cli/go/download/_ path.
-
-Learn how to create, invoke, and debug actions in your preferred development environment:
+Click on the language of your choice below to learn how to create and invoke an action using OpenWhisk for
+that language. If your preferred language isn't supported directly, you may find the
+[native binary](#creating-native-actions) or [Docker](#creating-docker-actions) action path more suitable.
+Multiple actions may be composed together to create a longer processing pipeline called a
+[sequence](#creating-action-sequences).
 
 * [JavaScript](#creating-and-invoking-javascript-actions)
 * [Swift](#creating-swift-actions)
@@ -46,13 +45,18 @@ Learn how to create, invoke, and debug actions in your preferred development env
 * [Go](#creating-go-actions)
 * [Native binaries](#creating-native-actions)
 
-In addition, learn about:
+Each invocation of an action results in an activation record that is identified by a unique
+activation ID. The input to an action and the result of an action are a dictionary of key-value
+pairs, where the key is a string and the value a valid JSON value.
+
+In addition, we recommend that you review the following topics:
 
 * [Watching action output](#watching-action-output)
 * [Getting actions](#getting-actions)
 * [Listing actions](#listing-actions)
 * [Deleting actions](#deleting-actions)
 * [Accessing action metadata within the action body](#accessing-action-metadata-within-the-action-body)
+* [Securing your action](./security.md)
 
 ## Creating and invoking JavaScript actions
 
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 0000000000..b8a87df3da
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,37 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# Securing your actions
+
+The actions that you create will run in a sandboxed environment, namely a container. The code that you
+write nonetheless should follow best practices to ensure that the code is reasonably secure against remote
+code exploits and malicious inputs. You should also be cognizant of the packages you bundle and check them
+routinely for vulnerabilities.
+
+There are several considerations to be mindful of when authoring actions:
+
+- **Sanitize Function Arguments:** Every invocation of the action receives input arguments which may be from untrusted sources.
+- **Check Dependencies for Vulnerabilities:** When bundling third party dependencies, you should be aware of any vulnerabilities you inherit.
+- **Authenticate Requests:** When using [web actions](webactions.md#securing-web-actions), you can enable built-in authentication to reject unwanted requests.
+- **Seal Parameters:** Parameters with pre-defined values may be sealed when used with [web actions](webactions.md#protected-parameters) to prevent parameter hijacking.
+
+Actions which are vulnerable to code injection attacks or parameter hijacking could end up leaking bound
+action parameters, or worse persisting malicious code within the sandbox for the lifetime of the function
+execution. Moreover, an action sandbox may be reused for more than one function invocation, and hence an
+attacker could persist their code for the lifetime of the sandbox as well.


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services