This is an automated email from the ASF dual-hosted git repository.
csantanapr pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk.git
The following commit(s) were added to refs/heads/master by this push:
new adf3ba1 add a doc for securing actions (#3801)
adf3ba1 is described below
commit adf3ba1b2cb76d2b4eb09eff3f360bf14bd65623
Author: rodric rabbah <[email protected]>
AuthorDate: Mon Jun 25 19:02:55 2018 -0400
add a doc for securing actions (#3801)
* Updates to actions doc to remove redundant list of action runtimes, other
cleanup. Add link to securing actions.
* Fix typo.
---
docs/actions.md | 34 +++++++++++++++++++---------------
docs/security.md | 37 +++++++++++++++++++++++++++++++++++++
2 files changed, 56 insertions(+), 15 deletions(-)
diff --git a/docs/actions.md b/docs/actions.md
index c7fbd99..3a9867f 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 0000000..b8a87df
--- /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.
