163 lines
5.0 KiB
Markdown
163 lines
5.0 KiB
Markdown
# Action Parameter Delivery
|
|
|
|
This directory contains documentation for Attune's secure parameter passing system for actions.
|
|
|
|
## Quick Links
|
|
|
|
- **[Parameter Delivery Guide](./parameter-delivery.md)** - Complete guide to parameter delivery methods, formats, and best practices (568 lines)
|
|
- **[Quick Reference](./QUICKREF-parameter-delivery.md)** - Quick decision matrix and copy-paste templates (365 lines)
|
|
|
|
## Overview
|
|
|
|
Attune provides three methods for delivering parameters to actions, with **stdin + JSON as the secure default** (as of 2025-02-05):
|
|
|
|
### Delivery Methods
|
|
|
|
| Method | Security | Use Case |
|
|
|--------|----------|----------|
|
|
| **stdin** (default) | ✅ High | Credentials, structured data, most actions |
|
|
| **env** (explicit) | ⚠️ Low | Simple non-sensitive shell scripts only |
|
|
| **file** | ✅ High | Large payloads, complex configurations |
|
|
|
|
### Serialization Formats
|
|
|
|
| Format | Best For | Example |
|
|
|--------|----------|---------|
|
|
| **json** (default) | Python/Node.js, structured data | `{"key": "value"}` |
|
|
| **dotenv** | Shell scripts, simple key-value | `KEY='value'` |
|
|
| **yaml** | Human-readable configs | `key: value` |
|
|
|
|
## Security Warning
|
|
|
|
⚠️ **Environment variables are visible in process listings** (`ps aux`, `/proc/<pid>/environ`)
|
|
|
|
**Never use `env` delivery for sensitive parameters** like passwords, API keys, or tokens.
|
|
|
|
## Quick Start
|
|
|
|
### Secure Action (Default - No Configuration Needed)
|
|
|
|
```yaml
|
|
# action.yaml
|
|
name: my_action
|
|
ref: mypack.my_action
|
|
runner_type: python
|
|
entry_point: my_action.py
|
|
# Uses default stdin + json (no need to specify)
|
|
|
|
parameters:
|
|
type: object
|
|
properties:
|
|
api_key:
|
|
type: string
|
|
secret: true
|
|
```
|
|
|
|
```python
|
|
# my_action.py
|
|
import sys, json
|
|
|
|
# Read from stdin (the default)
|
|
content = sys.stdin.read()
|
|
params = json.loads(content.split('---ATTUNE_PARAMS_END---')[0])
|
|
api_key = params['api_key'] # Secure - not in process list!
|
|
```
|
|
|
|
### Simple Shell Script (Non-Sensitive - Explicit env)
|
|
|
|
```yaml
|
|
# action.yaml
|
|
name: simple_script
|
|
ref: mypack.simple_script
|
|
runner_type: shell
|
|
entry_point: simple.sh
|
|
# Explicitly use env for non-sensitive data
|
|
parameter_delivery: env
|
|
parameter_format: dotenv
|
|
```
|
|
|
|
```bash
|
|
# simple.sh
|
|
MESSAGE="${ATTUNE_ACTION_MESSAGE:-Hello}"
|
|
echo "$MESSAGE"
|
|
```
|
|
|
|
## Key Features
|
|
|
|
- ✅ **Secure by default** - stdin prevents process listing exposure
|
|
- ✅ **Type preservation** - JSON format maintains data types
|
|
- ✅ **Automatic cleanup** - Temporary files auto-deleted
|
|
- ✅ **Flexible formats** - Choose JSON, YAML, or dotenv
|
|
- ✅ **Explicit opt-in** - Only use env when you really need it
|
|
|
|
## Environment Variables
|
|
|
|
All actions receive these metadata variables:
|
|
|
|
- `ATTUNE_PARAMETER_DELIVERY` - Method used (stdin/env/file)
|
|
- `ATTUNE_PARAMETER_FORMAT` - Format used (json/dotenv/yaml)
|
|
- `ATTUNE_PARAMETER_FILE` - File path (file delivery only)
|
|
- `ATTUNE_ACTION_<KEY>` - Individual parameters (env delivery only)
|
|
|
|
## Breaking Change Notice
|
|
|
|
**As of 2025-02-05**, the default parameter delivery changed from `env` to `stdin` for security.
|
|
|
|
Actions that need environment variable delivery must **explicitly opt-in** by setting:
|
|
|
|
```yaml
|
|
parameter_delivery: env
|
|
parameter_format: dotenv
|
|
```
|
|
|
|
This is allowed because Attune is in pre-production with no users or deployments (per AGENTS.md policy).
|
|
|
|
## Best Practices
|
|
|
|
1. ✅ **Use default stdin + json** for most actions
|
|
2. ✅ **Mark sensitive parameters** with `secret: true`
|
|
3. ✅ **Only use env explicitly** for simple, non-sensitive shell scripts
|
|
4. ✅ **Test credentials don't appear** in `ps aux` output
|
|
5. ✅ **Never log sensitive parameters**
|
|
|
|
## Example Actions
|
|
|
|
See the core pack for examples:
|
|
|
|
- `packs/core/actions/http_request.yaml` - Uses stdin + json (handles API tokens)
|
|
- `packs/core/actions/echo.yaml` - Uses env + dotenv (no secrets)
|
|
- `packs/core/actions/sleep.yaml` - Uses env + dotenv (no secrets)
|
|
|
|
## Documentation Structure
|
|
|
|
```
|
|
docs/actions/
|
|
├── README.md # This file - Overview and quick links
|
|
├── parameter-delivery.md # Complete guide (568 lines)
|
|
│ ├── Security concerns
|
|
│ ├── Detailed method descriptions
|
|
│ ├── Format specifications
|
|
│ ├── Configuration syntax
|
|
│ ├── Best practices
|
|
│ ├── Migration guide
|
|
│ └── Complete examples
|
|
└── QUICKREF-parameter-delivery.md # Quick reference (365 lines)
|
|
├── TL;DR
|
|
├── Decision matrix
|
|
├── Copy-paste templates
|
|
├── Common patterns
|
|
└── Testing tips
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
1. **Quick decisions**: See [QUICKREF-parameter-delivery.md](./QUICKREF-parameter-delivery.md)
|
|
2. **Detailed guide**: See [parameter-delivery.md](./parameter-delivery.md)
|
|
3. **Check delivery method**: Look at `ATTUNE_PARAMETER_DELIVERY` env var
|
|
4. **Test security**: Run `ps aux | grep attune-worker` to verify secrets aren't visible
|
|
|
|
## Summary
|
|
|
|
**Default**: `stdin` + `json` - Secure, structured, type-preserving parameter passing.
|
|
|
|
**Remember**: stdin is the default. Environment variables require explicit opt-in! 🔒 |