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:
[email protected]


With regards,
Apache Git Services

Reply via email to