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 <rod...@gmail.com> 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.