DEV Community: Paul SANTUS

Cloud Native Buildpack for AWS Lambda PHP (Bref) - technical detail

Paul SANTUS — Wed, 29 Jul 2026 22:00:00 +0000

In first post of this series, I introduced my Cloud Native Buildpack for AWS Lambda PHP (Bref).

Here I want to provide some technical details on how it works so far.

Lambda's /var/task problem

CNB places the application at /workspace. Lambda requires it at /var/task. And you can't override LAMBDA_TASK_ROOT, as it's a reserved environment variable.

The buildpack runs as a non-root user during certain CNB phases, so it can't write to /var/task either. The solution is a thin flatten step after the CNB build that copies /workspace to /var/task and restores the Bref entrypoint. This is handled automatically by make lambda.

Is it elegant? Not perfectly. But it works, and the developer never sees it.

Extension installation: three fallback strategies

Bref's extra PHP extensions are published as Docker images (e.g., bref/extra-gd-php-84:3). Each image is a FROM scratch layer containing just the .so file and its dependencies under /opt.

The buildpack uses a three-tier strategy to install extensions:

Method 1: crane. It uses go-containerregistry to pull and extract the extension image directly from Docker Hub, no Docker daemon needed. Works great in CI. However, bref-extra only publishes x86_64 images (ARM64 is not supported by the bref-extra project).

Method 2: docker create + cp. It falls back to the Docker daemon if crane fails. Same limitation: x86 only.

Method 3: Compile from source. When neither method works (ARM deployments), the buildpack compiles extensions from source using the Bref build image's toolchain. This is the same approach used in multi-stage Dockerfiles but automated via build recipes.

The recipes file (lib/extension-recipes.sh) defines how to build each extension: what system packages to install, what configure flags to pass, where to download external source. Currently supports gd, redis, imagick, amqp, soap, ftp, gmp, pgsql, uuid, yaml, mongodb, calendar, and exif.

How bref-extra extensions are built

Looking at the bref-extra repo, each extension uses a two-stage Dockerfile:

FROM bref/build-php-$PHP_VERSION:$BREF_VERSION AS ext
# compile the extension...
RUN cp "$(php-config --extension-dir)/redis.so" /tmp/redis.so
RUN php /bref/lib-copy/copy-dependencies.php /tmp/redis.so /tmp/extension-libs

FROM scratch
COPY --from=ext /tmp/redis.so /opt/bref/extensions/redis.so
COPY --from=ext /tmp/ext.ini /opt/bref/etc/php/conf.d/ext-redis.ini
COPY --from=ext /tmp/extension-libs /opt/lib

The final published image is literally just /opt with the compiled artifacts. That's what crane extracts during our build. And for ARM, our recipes replicate that first stage at build time.

Cloud Native Buildpack for Bref: build your app for Lambda in one command

Paul SANTUS — Tue, 28 Jul 2026 13:29:23 +0000

I've been deploying PHP applications to AWS Lambda with Bref for a while now. Since I'm a Terraform fan, I very quickly parted with @mnapoli's serverless.yml approach, in favour a Terraform + container-based Lambdas.

Here, the Dockerfile approach works, but it's verbose: a typical multi-stage Dockerfile for a Symfony app on Lambda is 100+ lines of repetitive infrastructure code.

Recently, Cloud Native Buildpacks (CNB) caught my attention. Their promise is to turn source code into container images without a Dockerfile, with built-in layer caching and a standardized build/run separation. The question was: could this work for Lambda?

The challenge

Lambda container images have specific requirements that don't align perfectly with the CNB model:

Lambda expects the app at /var/task (a reserved, non-overridable path)
Lambda needs a specific entrypoint (/lambda-entrypoint.sh for Bref)
The CNB lifecycle adds its own launcher binary that Lambda doesn't understand
Bref base images use Amazon Linux with stripped-down package managers

None of these are showstoppers, but they required creative solutions.

What my buildpack does

Given a PHP project with bref/bref in its composer.json, the buildpack handles everything:

Detects the app (composer.json + bref dependency)
Installs PHP extensions (via crane download or from-source compilation)
Runs composer install with production optimizations
Configures OPcache for Lambda cold starts
Detects Symfony and warms the cache
Produces a Lambda-ready container image

The entire configuration is driven by environment variables:

make lambda \
  TEST_APP_PATH=./my-symfony-app \
  LAMBDA_IMAGE=my-app \
  BP_BREF_RUNTIME=fpm \
  BP_BREF_EXTENSIONS=redis,gd,soap \
  BP_OPCACHE_JIT=true

Compare that to 120 lines of multi-stage Dockerfile with extension compilation, vendor optimization, cache warmup, and OPcache tuning.

Testing it for real

I deployed the Symfony Demo application to Lambda using the buildpack. Same app, same database, same environment variables as the existing layer-based deployment. Only change: it's just built with pack build instead of docker build and a long multi-stage Docker file.

It works. The function URL serves the app correctly, Symfony cache is pre-warmed, and the second build reuses all cached layers (vendor, opcache config) making rebuilds near-instant when only application code changes.

I also tested extension compilation: ftp and soap compile successfully from PHP source on ARM64 during the build step, with proper shared library dependency resolution via Bref's copy-dependencies.php.

What's not handled by the buildpack

The buildpack builds your app into a Lambda container image. It does not:

Set up your Symfony app for Bref (you still need BrefKernel, trusted_proxies, etc.)
Serve static assets (CSS/JS need CloudFront + S3, same as any Bref deployment)
Replace your IaC (you still need Terraform/CDK/Serverless to create the Lambda function)

It replaces the Dockerfile and the build process, not the infrastructure or app configuration.

Current state

The buildpack is published and usable today:

GitHub: https://github.com/psantus/bref-buildpack
Docker Hub: psantus/bref-buildpack:0.2.0
CNB Registry: bref/php-lambda (registered at registry.buildpacks.io)
CI: passing on GitHub Actions
Tested: Symfony Demo running on Lambda ARM64 (Graviton) via function URL

It supports PHP 8.2/8.3/8.4, ARM and x86 architectures, extension compilation from source, all 40+ bref-extra extensions (x86) or compile-from-source (ARM), Symfony auto-detection, composer caching, OPcache/JIT configuration, and vendor shrinking.

Try it

brew install buildpacks/tap/pack
git clone https://github.com/psantus/bref-buildpack
cd bref-buildpack
make lambda TEST_APP_PATH=/path/to/your/php/app LAMBDA_IMAGE=my-lambda BP_BREF_EXTENSIONS=gd,redis

The resulting image is ready to push to ECR and deploy to Lambda.

Serverless Lazy Generation: generate once, cache forever with CloudFront origin groups (+ S3 and Lambda)

Paul SANTUS — Sat, 25 Jul 2026 14:14:08 +0000

Sometimes, your business app may have to be ready to serve millions of assets generated from your data (invoice PDFs, text-to-speech audio files, etc.), only a small fraction of which will actually be requested by users.

When such assets generation is expensive, the naive approach - pre-generate every asset - leads to a lot of wasted compute: you generate assets that may never be requested.

Pre-generation may also cause bottlenecks (adding 1,000 new articles means synthesizing 1,000 audio files before they're available), storage bloat (you're paying to store assets that may never see a single request), and staleness (when content changes, you need a pipeline to detect and regenerate affected assets).

What if you could flip this model? Generate assets only when requested, cache them permanently, and never generate the same asset twice.

In this post, I'll walk through a complete serverless architecture that uses CloudFront's native failover mechanism to implement lazy audio generation with Amazon Polly. The same pattern applies to image thumbnails, PDF rendering, video transcoding, or any expensive asset generation.

Architecture Overview: The CloudFront Origin Group Pattern

The key insight is that CloudFront Origin Groups support automatic failover. You configure a primary origin (S3) and a failover origin (API Gateway + Lambda). When the primary returns a 403 or 404, CloudFront transparently routes the request to the failover origin: no client-side retry, no custom logic.

This gives us a clean separation:

Component	Role
S3 (primary origin)	Serves cached audio files. Acts as a permanent cache.
API Gateway + Lambda (failover origin)	Generates audio on-demand when S3 returns 404.
Amazon Polly	Converts text to speech (the expensive operation).
CloudFront	Edge caching + origin failover orchestration.

The beauty is that once Lambda generates an audio file and stores it in S3, all subsequent requests are served directly from S3 (or CloudFront's edge cache). Lambda never executes again for that asset.

How It Works

(full-disclosure: from this point onwards, the post is AI-generated)

First Request (Cache Miss)

Client requests https://d1234.cloudfront.net/audio/welcome.mp3
CloudFront checks its edge cache — miss. Routes to the Origin Group.
S3 (primary origin) returns 404 — the file doesn't exist yet.
CloudFront detects the 404 and fails over to the secondary origin.
API Gateway receives the request and invokes Lambda.
Lambda reads the source text from s3://bucket/texts/welcome.txt.
Lambda calls Amazon Polly to synthesize speech from the text.
Lambda stores the generated MP3 at s3://bucket/audio/welcome.mp3.
Lambda returns the MP3 binary (base64-encoded) with Cache-Control: public, max-age=31536000.
CloudFront caches the response at the edge and returns it to the client.

Second Request (Cache Hit)

Client requests https://d1234.cloudfront.net/audio/welcome.mp3
CloudFront checks its edge cache — hit. Returns immediately.

If the edge cache has expired:

CloudFront routes to the Origin Group.
S3 (primary origin) returns 200 — the file exists.
CloudFront caches and returns the response. Lambda is never invoked.

Key Components

Below I detail the components of the solution I share in my sample GitHub repo. My use case is for Text-to-Speech generation with Polly, but you can adapt it to your own.

CloudFront Origin Group

The Origin Group is the orchestration layer. It defines:

A primary origin (S3 with OAC) for serving cached content
A failover origin (API Gateway) for on-demand generation
Failover criteria: HTTP 403 and 404 status codes

This is infrastructure-level routing — no application code needed to handle caching logic.

S3 as a Permanent Cache

S3 serves dual purpose:

Source storage: Text files live at texts/{filename}.txt
Cache storage: Generated audio lives at audio/{filename}.mp3

The S3 bucket is not publicly accessible. CloudFront accesses it via Origin Access Control (OAC), and Lambda accesses it via IAM role permissions.

Lambda as the Generator

The Lambda function is lean — its only job is:

Read the source text from S3
Call Polly to synthesize audio
Store the result back in S3
Return the audio to the caller

It includes a belt-and-suspenders check: before calling Polly, it verifies the audio doesn't already exist in S3 (handling race conditions where multiple simultaneous first-requests hit Lambda).

Amazon Polly for TTS

Polly provides neural and standard voices for text-to-speech synthesis. In this architecture, we use the standard engine with the Joanna voice and MP3 output format. Polly charges per character synthesized — another reason lazy generation saves money.

Benefits

Zero cold starts for cached content. Once generated, audio is served from S3 or CloudFront's edge — sub-10ms latency worldwide. Lambda cold starts only affect the very first request for each asset.

Infinite scalability. S3 and CloudFront scale to any traffic level without configuration. The generation layer (Lambda) only handles the small fraction of requests that are cache misses.

Pay only for generation once. Each audio file is synthesized exactly once. After that, you're paying only S3 storage ($0.023/GB/month) and CloudFront data transfer.

CloudFront edge caching. Popular content is served from 400+ edge locations worldwide. Your users get sub-50ms response times regardless of where the origin bucket lives.

Zero maintenance. No cron jobs, no batch pipelines, no cache invalidation logic. The system is self-healing — if you delete a cached file, it regenerates on next request.

Cost Analysis

Let's compare pre-generation vs. lazy generation for a platform with 10,000 text articles:

Pre-Generation Approach

Item	Cost
Polly: 10,000 articles × 2,000 chars avg	$16.00 (standard voice)
S3 storage: 10,000 × 500KB avg	$0.12/month
Lambda compute: 10,000 invocations × 5s avg	$0.83
Total upfront	$16.95

You pay this every time content changes and you re-run the batch.

Lazy Generation Approach (assuming 20% of content is ever requested)

Item	Cost
Polly: 2,000 articles × 2,000 chars avg	$3.20
S3 storage: 2,000 × 500KB avg	$0.02/month
Lambda compute: 2,000 invocations × 5s avg	$0.17
CloudFront requests (all 10K articles, cached)	$0.01
Total	$3.40

80% cost reduction — and you never pay for content nobody reads.

Code Walkthrough

Lambda Handler Highlights

import json
import re
import os
import base64
import boto3

s3 = boto3.client("s3")
polly = boto3.client("polly")
BUCKET = os.environ["BUCKET_NAME"]

def handler(event, context):
    path = event.get("path", "")
    match = re.search(r"/audio/(.+)\.mp3$", path)
    if not match:
        return {"statusCode": 400, "body": "Invalid path"}

    filename = match.group(1)

    # Belt-and-suspenders: check if already generated (race condition guard)
    try:
        existing = s3.get_object(Bucket=BUCKET, Key=f"audio/{filename}.mp3")
        audio_bytes = existing["Body"].read()
    except s3.exceptions.NoSuchKey:
        # Read source text
        text_obj = s3.get_object(Bucket=BUCKET, Key=f"texts/{filename}.txt")
        text = text_obj["Body"].read().decode("utf-8")

        # Synthesize with Polly
        response = polly.synthesize_speech(
            Text=text, OutputFormat="mp3",
            VoiceId="Joanna", Engine="standard"
        )
        audio_bytes = response["AudioStream"].read()

        # Cache to S3 (non-fatal if this fails)
        try:
            s3.put_object(
                Bucket=BUCKET, Key=f"audio/{filename}.mp3",
                Body=audio_bytes, ContentType="audio/mpeg"
            )
        except Exception:
            pass  # Audio still returned even if caching fails

    return {
        "statusCode": 200,
        "headers": {
            "Content-Type": "audio/mpeg",
            "Cache-Control": "public, max-age=31536000"
        },
        "body": base64.b64encode(audio_bytes).decode("utf-8"),
        "isBase64Encoded": True
    }

Terraform Highlights: Origin Group Configuration

resource "aws_cloudfront_distribution" "cdn" {
  # Primary origin: S3 with OAC
  origin {
    domain_name              = aws_s3_bucket.assets.bucket_regional_domain_name
    origin_id                = "s3-assets"
    origin_access_control_id = aws_cloudfront_origin_access_control.oac.id
  }

  # Failover origin: API Gateway
  origin {
    domain_name = "${aws_api_gateway_rest_api.api.id}.execute-api.us-east-1.amazonaws.com"
    origin_id   = "api-fallback"
    origin_path = "/live"
    custom_origin_config {
      http_port              = 80
      https_port             = 443
      origin_protocol_policy = "https-only"
      origin_ssl_protocols   = ["TLSv1.2"]
    }
  }

  # Origin Group: failover on 403/404
  origin_group {
    origin_id = "s3-with-fallback"
    failover_criteria {
      status_codes = [403, 404]
    }
    member { origin_id = "s3-assets" }
    member { origin_id = "api-fallback" }
  }

  # Route /audio/* through the origin group
  ordered_cache_behavior {
    path_pattern     = "/audio/*"
    target_origin_id = "s3-with-fallback"
    # Uses CachingOptimized managed policy
    cache_policy_id  = "658327ea-f89d-4fab-a63d-7e88639e58f6"
    viewer_protocol_policy = "redirect-to-https"
    allowed_methods  = ["GET", "HEAD"]
    cached_methods   = ["GET", "HEAD"]
  }
}

The key is the origin_group block — CloudFront handles all failover logic natively.

Deployment

# Clone the repository
cd serverless-lazy-generation

# Add your text files
echo "Welcome to our platform." > sample-texts/welcome.txt
echo "This is a demo of lazy generation." > sample-texts/demo.txt

# Deploy with Terraform
cd terraform
terraform init
terraform plan
terraform apply

# Note the outputs
# cloudfront_url = "https://d1234abcdef.cloudfront.net"
# sample_audio_url = "https://d1234abcdef.cloudfront.net/audio/welcome.mp3"

Testing

# Get the CloudFront URL from Terraform output
CF_URL=$(terraform -chdir=terraform output -raw cloudfront_url)

# First request — triggers generation (slower, ~2-5 seconds)
time curl -o welcome.mp3 "${CF_URL}/audio/welcome.mp3"

# Second request — served from cache (fast, <100ms)
time curl -o welcome2.mp3 "${CF_URL}/audio/welcome.mp3"

# Verify the files are identical
md5 welcome.mp3 welcome2.mp3

# Check response headers for cache status
curl -I "${CF_URL}/audio/welcome.mp3"
# Look for: X-Cache: Hit from cloudfront

# Request a non-existent text (should return 404)
curl -v "${CF_URL}/audio/nonexistent.mp3"

Extensions: Other Use Cases

The lazy generation pattern isn't limited to audio. Any expensive, deterministic transformation works:

Use Case	Source	Generator	Output
Image thumbnails	Original images in S3	Lambda + Sharp	Resized images
PDF generation	HTML templates + data	Lambda + Puppeteer	PDF documents
Video transcoding	Source video in S3	Lambda + FFmpeg	Transcoded video
Open Graph images	Article metadata	Lambda + Canvas	Social preview images
Map tiles	Vector data	Lambda + Mapbox GL	Raster tiles

For each case, the pattern is identical:

S3 stores the output (acts as cache)
CloudFront Origin Group fails over to Lambda on 404
Lambda generates, caches to S3, and returns
All subsequent requests bypass Lambda entirely

Conclusion

The serverless lazy generation pattern gives you the best of both worlds: the simplicity of static file serving with the flexibility of on-demand generation. CloudFront Origin Groups handle all the routing logic at the infrastructure level — no caching libraries, no invalidation jobs, no state management.

The architecture is:

Self-healing: Delete a cached file, and it regenerates on next request
Cost-efficient: You only pay to generate content that's actually consumed
Globally fast: CloudFront edge caching provides sub-50ms responses worldwide
Zero-ops: No servers to manage, no batch jobs to monitor, no cache to warm

Whether you're building a content platform, an accessibility layer, or a media processing pipeline, this pattern scales from zero to millions of assets with no code changes.

The complete source code — Lambda function, Terraform infrastructure, and sample texts — is available in the repository. Deploy it in under 5 minutes and start generating audio on demand.

Zipping 15Gb of S3 files in 6s. How the power of community made it possible.

Paul SANTUS — Thu, 25 Jun 2026 18:23:01 +0000

In my first article, I showed how parallelizing zip assembly across multiple Lambdas can beat the single-Lambda bandwidth ceiling. I zipped 6.9GB in 35 seconds with just 5 workers.

Since then, Jérémie published a follow-up article where a contributor (Fitz) introduced a brilliant optimization: UploadPartCopy. Instead of downloading (or even streaming) big files through Lambda just to upload them back into the zip, you can tell S3 to copy them server-side. This halves the bandwidth requirement and brought his single-Lambda solution down to 106 seconds.

I took Fitz's UploadPartCopy idea and combined it with my parallel approach. Here's what happened.

What I took from Jérémie and Fitz

The UploadPartCopy insight is elegant: since ZIP STORE mode has deterministic offsets, we know exactly where each file's data lands in the final archive. For big files (≥5MB), we can:

Write just the local file header (50 bytes) in an UploadPart
Have S3 copy the file data directly via UploadPartCopy — no download, no upload, instant

This means workers barely use any memory or bandwidth for big files.

Only issue is that S3 multipart upload API requires all segments (except the last one) to be bigger than 5MB. So the local file header needs to be appended to an another file (or group of files).

My planner Lambda groups small files together until they reach 5MB, appends the LOC header of the next big file, then the worker fires an UploadPartCopy for that big file's data.

When we run out of small files, we stream the smallest remaining big file and pair it with (the LOC header then) a copy of the largest remaining one.

For CRC32 (required in zip headers): files uploaded with modern AWS SDKs already have CRC32 stored as object metadata. A simple HeadObject call retrieves it — no need to read the file.

Step Functions: three limitations

My original architecture used Step Functions to orchestrate workers. Here's what I hit.

1. Inline Map caps at ~40 concurrent iterations

The AWS documentation says the Inline Map state supports "up to 40 concurrent iterations." In practice I saw up to 55, but never more. With 1500 duos to process, Step Functions queued them in batches of 55.

I switched to Distributed Map which launches Express child workflow executions. All 1120 iterations started within 2 seconds. Problem solved? Not quite.

2. Distributed Map: fast to dispatch, slow to collect

With Distributed Map, all workers started within 2 seconds. Every single one finished in under 1 second (mostly UploadPartCopy calls). Total Lambda compute: ~500ms average.

Yet the Map state took 38 seconds to complete.

The bottleneck? Step Functions' internal machinery for collecting and aggregating results from 1120 Express child executions. I confirmed: all workers started at 10:06:52-53, all finished by 10:06:54, but the Map state didn't report success until 10:07:28. 35 seconds of pure orchestration overhead.

3. The 256KB payload limit

Step Functions states can pass at most 256KB between them. With 3000 files:

The planner's assignment list exceeds 256KB → had to write to S3
The aggregated worker results exceed 256KB → had to write CRC32s to S3, read them back in the finalizer

This added complexity and latency (the finalizer reading 1500 small S3 files — 29 seconds sequentially, until I parallelized it down to 1.5s).

After all these fixes, the Step Functions version ran in 41 seconds for 3000 × 5MB files. Respectable — 2.5× faster than Jérémie's 106s — but I knew most of that time was Step Functions overhead, not actual work.

The final version: direct Lambda invocation

I stripped out Step Functions entirely and wrote a single orchestrator Lambda that:

Lists files, computes zip layout (the job of the "planner" Lambda in my StepFunction architecture), and initiates multipart upload (~0.5s)
Invokes all worker Lambdas synchronously in parallel using goroutines + the Lambda SDK (~0.5s to dispatch)
Collects results (workers return inline, no S3 round-trip for parts)
Reads CRC32 files from S3 in parallel, builds central directory, completes multipart upload (~1s)

Orchestrator Lambda (15min timeout, 1024MB)
    │
    ├─── goroutine → Invoke Worker 1 (sync) → return {parts}
    ├─── goroutine → Invoke Worker 2 (sync) → return {parts}
    ├─── ...
    └─── goroutine → Invoke Worker N (sync) → return {parts}
    │
    └─── All done → Build CD → CompleteMultipartUpload

The Lambda SDK's synchronous Invoke blocks until the worker returns. With 200 concurrent goroutines, all workers are dispatched instantly. No orchestration overhead, no state size limits for the parts (only CRC32s go to S3), no 35-second result aggregation.

Now the theoretical time is: orchestration time + time to upload the smallest large file that stays orphan after we pair all large files with groups of small files or single large files

Results: 3000 × 5MB benchmark

Approach	Time	Notes
Jérémie Gen1 (Rust, streaming)	212s	Single Lambda, 512MB
Jérémie Gen2 (Rust, UploadPartCopy)	106s	Single Lambda, 640MB
My Step Functions version	41s	Distributed Map, 1120 workers
My orchestrator Lambda	6s	Direct invoke, ~1500 workers

6 seconds to zip 15GB into a single valid ZIP64 archive. That's a 18× improvement over the optimized single-Lambda approach, and 35× over the original.

Worker stats:

Max memory: 85 MB (I initially allocated 3008MB — massively over-provisioned thanks to UploadPartCopy)
Average duration: 516ms per worker
Max duration: 1035ms

What I learned (round 2)

Step Functions Parallel Map adds seconds, not milliseconds. For latency-sensitive fan-out/fan-in, direct Lambda invocation is faster. Step Functions shines when you need retries, visual debugging, long-running workflows, or error handling, or lightning fast step transition speed. This outstanding performance lasts only until you need more than 40 parallel processes.
UploadPartCopy is the killer optimization. When most files are ≥5MB, workers barely do any work — they just tell S3 to copy data server-side. Memory stays under 100MB regardless of file sizes.
The orchestrator pattern is underrated. A single Lambda with goroutines can invoke hundreds of child Lambdas synchronously, collect results, and finalize — all within one execution context. No state machine, no payload limits between states, no aggregation overhead.
Over-parallelization can hurt. 1500 separate assignments created more Step Functions overhead than the actual compute. Grouping into fewer, larger batches would have been better for the SFN approach.

Try it

Code: github.com/psantus/on-demand-archive-on-s3

The repo has both approaches: Step Functions (cmd/planner + cmd/worker + cmd/finalizer) and the orchestrator Lambda (cmd/orchestrator).

Jérémie's challenge repo: github.com/RustyServerless/demo-s3-archiving

What's next?

The theoretical minimum is bounded by Lambda cold start time (~200ms) plus the slowest UploadPart call (if we lack small files, we may need to upload a large file manually to append another file's LOC to it) plus orchestrator overhead (~500ms).

Your move, Jérémie 😏

Edit: with 73.2Gb (15,000 files), my solutions gives quite acceptable performance. Just 20s (probably due to my 1000 account default concurrency, would likely be faster on an unbounded account :D)

Paul out.

AWS Security Agent: 34 Findings in Under 10 Hours. A Real-World Test

Paul SANTUS — Mon, 08 Jun 2026 12:00:34 +0000

Last week, I ran AWS Security Agent against an app I'm building for a client. The app is quite usual: a React front-end, and the backend is powered by a CMS (that's part of my customer's requirements) on top of which I built a custom API. Both run on Lambda, with DSQL as the database layer and quite a lot of AI inside (more on that below). The results were impressive.

Two scans, overnight

I kicked off both scans in the evening:

Code Review completed in 1h26m:

For this, I had to grant read access to my application Github repository (you can provide write access to get fixes, but that was a step I wasn't ready to take just yet.)
18 findings (9 High, 8 Medium, 1 Low) which covered SQL injection, SSRF, XSS, privilege escalation, secret exposure, IAM misconfigurations
2h42m of agent task time

Penetration Test completed in 7h56m:

The pentest was not a full blackbox test. It started with 3 URLs I provided (the app's front-end, the API and the admin app) but I also submitted the repository.
16 findings (2 Critical, 2 High, 12 Medium)
29.16 hours of agent task time

By the time I woke up, I had a downloadable 60+ page report with reproduction steps, CVSS scores, and suggested fixes. And a pleasant UI to see results summary, but also findings details, test logs, etc.

What impressed me

It thinks like a real Pentester

The agent didn't just scan for known CVEs. It understood my application's architecture and chained vulnerabilities together:

It discovered that some API method had no authentication
It found that the some Lambda code called by a Step Function this method was triggering constructed a URL with user-supplied (non-protected) lang parameter
It crafted a payload using # fragment to redirect requests to an attacker-controlled domain it owned
It verified the SSRF by actually receiving DNS callbacks!!

That's a multi-step attack requiring deep understanding of Python's URL parsing, AWS Step Functions workflow, and the application's data flow from API to Lambda to Wikipedia API.
(I provided the repo )

SQL injection: genuinely clever

The code review found a SQL injection vector I would never have caught manually. Our DSQL driver had a shortcut: if a value starts with CAST(, it's passed through unescaped (intended for internal type conversions). The agent traced the full path from user input (POST /api/my-route body) through the CMS' abstraction layer down to the raw pg_query() call, proving the injection was reachable.

A unexpected category.

I was expecting the Agent to report SSRF, path traversal, etc. One category I didn't expect was "Cost Abuse". Since my app runs on serverless, the Agent also provided valuable insights on path were attackers could make my AWS bill fat, especially via the use of Bedrock, Polly and other AI services.

Findings were validated through exploitation

The penetration test didn't just flag theoretical issues. A bug let the CMS "Installation Wizard" accessible even once install once done. AWS Security Agent

Accessed the install page without auth
Successfully connected to the production database (DSQL with IAM auth meant empty credentials worked)
Enumerated installed plugins with exact version numbers
Documented each step with HTTP requests and responses

Both approaches brought original content

Despite the white box approach, only half of findings were redundant. The code review caught architectural issues (IAM over-privilege due to several Lambdas sharing the same IAM role, hardcoded secrets, missing log retention) while the pentest found runtime exploitables (auth bypass, path traversal, IDOR). Together they covered more ground than either alone.

A word on cost

Warning: AWS Security Agent CAN be expensive (yet cost-effective): at standard pricing of $50/agent-hour, the total would have been:

Code review: 2.7h × $50 = $135
Pentest: 29.2h × $50 = $1,460
Total: ~$1,595

For context, a human pentest engagement of equivalent scope (3 URLs, mixed tech stack, 8 hours of active testing) would probably run $8,000–$20,000 and take 1-2 weeks to deliver results.

But here's the kicker: AWS Security Agent includes a generous free tier. New customers get a 2-month trial with up to 400 pentesting task-hours per month. Both my scans (31.8 task-hours total) fit comfortably within that allowance. So the first real-world security audit of my production application cost me exactly $0.

From Findings to Fixes

The actionable output let me fix all findings within a single day:

SQL injection → removed CAST bypass, added intval() on inputs
SSRF → URL scheme allowlist + private IP blocking
Auth bypass on install page → overlay file blocking access
Path traversal → regex validation on URL path parameters
Task token exposure → stripped from API response
Info disclosure → CloudFront response headers policy removes version headers
Missing logging → API Gateway access logs + 30-day retention

The suggested fixes in the report were specific enough to implement directly, not generic "validate your inputs" advice, but exact code locations and replacement patterns.

A few more things

To be exhaustive, I must share that

it didn't find existing application logic bugs (due to the model being instructed to focus solely on security. Attention is all we need, right?)
due to our white box nature of our pentest, a couple findings, while technically correct, required knowledge of our deployment model to be exploited. If you need to know the value of a secret "consider-i-m-an-admin" header, then maybe the risk is not high.. but again the agent thinks like security folks, and probably considered lateral movement after log access like a possible path.
Some findings are CMS upstream issues that I can't fix without modifying vendor code. I submitted findings to their security team.

Verdict

AWS Security Agent is not a full replacement for security expertise: you still need to understand your architecture to prioritize and fix findings. But as a first pass that runs overnight and produces a professional-grade report? It's remarkably good; literally 0 findings were non-relevant. The multi-step attack chains, the code-level precision, and the actual exploitation validation put it well above traditional SAST/DAST tools.

For a solo developer or small team shipping on AWS, this is a no-brainer at the free tier. Run it before every major release, fix what it finds, and sleep better.

S3 zipper challenge: a parallel zip assembly that beats the single Lambda approach

Paul SANTUS — Mon, 01 Jun 2026 21:27:25 +0000

I recently read Jérémie Rodon's excellent article On-Demand Archives on S3, where he describes an elegant Rust solution for zipping 3,000 × 5MB files from S3 within a single Lambda function.

His approach is impressive: streaming a ZIP archive through a custom Rotating Slab Buffer, saturating bandwidth with concurrent downloads, all within 512MB of RAM. The result: 3 minutes 35 seconds.

I thought it was a good challenge to reach better performance. His article ends with an open invitation: "do you think you can do better with your favorite language?" Well, my favorite language is not Rust nor Go nor.. however, I'm fluent in serverless ;) so I took a different angle entirely.

A Different Approach: Why Not Parallelize the Problem?

Jérémie's constraint was a single Lambda. That's elegant, but it means you're bound by one machine's network bandwidth (~600 Mbps). No matter how perfect your streaming is, physics wins: 15GB at 600 Mbps ≈ 200 seconds minimum.

My question was: what if we break that single-machine bottleneck?

The key insight is that ZIP files in STORE mode (no compression) have deterministic byte offsets. Each entry is exactly 50 + len(filename) + filesize bytes (local header + ZIP64 extra field + data). If you know all filenames and sizes upfront, you can pre-calculate exactly where every file will land in the final archive, before downloading a single byte.

This means independent workers can each build their portion of the zip in parallel, and S3's multipart upload lets them write their chunks independently (parts can be uploaded in any order by different processes sharing the same upload ID).

Architecture

Planner Lambda → Step Functions Distributed Map → N Worker Lambdas → Finalizer Lambda
     │                        │ │ │                        │
     │ CreateMultipartUpload  │ │ │ UploadPart (parallel)  │ CompleteMultipartUpload
     ▼                        ▼ ▼ ▼                        ▼
                         S3 Output Bucket

Planner: Lists all source files, computes zip byte offsets, initiates multipart upload, divides work into balanced batches (equal data volume per worker).
Workers (N concurrent): Each downloads its assigned files, constructs zip local file headers + raw data, computes CRC32 on the fly, streams to S3 as multipart parts.
Finalizer: Builds the central directory with real CRC32 values, uploads it as the final part, calls CompleteMultipartUpload.

Results

With a quota-constrained training account (I had 10 concurrency limit so used only 5 concurrent Lambdas, 3008MB each), zipping 6.9GB across 160 files:

Metric	Single Lambda (Jérémie's Rust)	Parallel (this project)
Approach	Stream within 1 Lambda	Fan-out N workers
Time (15GB, 3000 files)	~215s	Estimated ~10-15s with 100+ workers
Time (6.9GB, 160 files, 5 workers)	-	35s
Memory per worker	512MB	3008MB (could be lower)
Language	Rust 🦀	Go

With a production account (1000 concurrent Lambdas), the 3000 × 5MB scenario would complete in under 15 seconds (each worker handles ~150MB, downloads take ~2s at 600Mbps, upload ~2s). The bottleneck shifts from bandwidth to Lambda cold start (~200ms for Go on ARM64).

Tradeoffs

Jérémie's approach is simpler to deploy (one Lambda, no orchestration) and cheaper per invocation (512MB × 215s vs N × 3008MB × few seconds). It's the right choice when you want minimal infrastructure.

The parallel approach wins on wall-clock time, and dramatically so. It's the right choice when the user is waiting and you want the archive ready in seconds, not minutes.

	Single Lambda	Parallel Fan-Out
Wall-clock time	Bounded by bandwidth	Bounded by slowest worker
Complexity	Low	Medium (Step Functions + 3 Lambdas)
Cost per archive	Lower	Higher (more Lambda-seconds total)
Scalability	Fixed ceiling (~600Mbps)	Linear with concurrency
Memory efficiency	Excellent (512MB)	Good (3GB, could optimize)

If I were to use it in prod, there are plenty of room for optimization (our current Lambda used at most 1875mb, well below our allocated 3Gb, we could use Jérémie's streaming optimizations to cut that to by 10). Yet, we'd probably still have some overhead compared to Jeremie's solutions (cold starts, TLS negociations...) and so far it's just a vanity project :)

What I Learned

ZIP STORE mode is embarrassingly parallel: deterministic offsets mean zero coordination between workers during the data phase.
S3 multipart upload is the perfect primitive: parts uploaded out of order, by different processes, assembled by S3 at the end.
Step Functions Distributed Map is ideal for this pattern: it handles fan-out, concurrency limits, retries, and result collection.
The real bottleneck at scale is Lambda concurrency limits, not bandwidth or compute. With sufficient concurrency, you can zip 15GB in the time it takes to download one 5MB file.

Try It

The code is at github.com/psantus/on-demand-archive-on-s3.

And if you want to try Jérémie's challenge with the single-Lambda constraint, his demo project is at github.com/RustyServerless/demo-s3-archiving.

Both approaches are valid, it just depends on whether you're optimizing for simplicity or speed.

Keep the challenge going?

So, « do you think you can do better with your favorite ~~language~~ architecture?»

And what does "better" even mean for you? :)

Hackez votre AWS CLI pour ajouter le support CloudShell et transformer votre terminal en bastion

Paul SANTUS — Fri, 29 May 2026 12:43:23 +0000

J'utilise AWS CloudShell depuis la Console depuis un moment. C'est pratique : un shell pré-authentifié dans votre navigateur, directement dans la Console AWS. Mais je me suis toujours demandé : pourquoi je ne peux pas l'utiliser depuis mon terminal ? Pourquoi n'y a-t-il pas de commande aws cloudshell ?

Il s'avère que c'est possible. L'API existe, elle n'est simplement pas publique. Et une fois que vous avez accès à CloudShell en CLI, vous pouvez faire des choses intéressantes avec, comme utiliser un CloudShell attaché à un VPC comme bastion pour atteindre vos instances RDS privées.

Consultez le dépôt compagnon en lisant cet article.

CloudShell : une API non documentée

AWS CloudShell n'a pas de support officiel SDK ou CLI. Mais la Console doit bien communiquer avec quelque chose, non ? En regardant ce que fait le navigateur quand vous ouvrez CloudShell, vous pouvez rétro-ingénierer l'API.

Heureusement, Jérôme Guyon a déjà fait ce travail et publié un modèle de service compatible boto3. Son travail a rendu tout cela possible.

L'API est simple : créer des environnements, les démarrer/arrêter, créer des sessions, uploader/télécharger des fichiers. Le mécanisme de session utilise le protocole WebSocket de SSM sous le capot, ce qui signifie que session-manager-plugin (le même binaire qui fait tourner aws ssm start-session) peut se connecter aux sessions CloudShell.

Apprendre un nouveau tour à l'AWS CLI

L'AWS CLI a une fonctionnalité peu connue : aws configure add-model. Donnez-lui un modèle de service JSON, et soudain la CLI connaît un nouveau service. AWS utilise ça en interne pour les previews privées.

(Le modèle boto3 du dépôt de Jérôme a juste besoin d'un champ "version": "2.0" ajouté au niveau racine pour devenir compatible CLI.)

Exécutez :

aws configure add-model \
  --service-model file://cloudshell-cli-model.json \
  --service-name cloudshell

C'est tout. Maintenant j'ai aws cloudshell avec l'auto-complétion et tout :

$ aws cloudshell help

AVAILABLE COMMANDS
       create-environment
       create-session
       delete-environment
       describe-environments
       get-environment-status
       start-environment
       stop-environment
       ...

Se connecter à CloudShell depuis le terminal

Le workflow est simple :

# Créer ou trouver un environnement
aws cloudshell create-environment --region eu-west-1

# Attendre qu'il soit RUNNING
aws cloudshell get-environment-status --environment-id <ID> --region eu-west-1

# Créer une session et se connecter
session-manager-plugin "$(aws cloudshell create-session \
  --environment-id <ID> \
  --session-type TMUX \
  --tab-id "$(uuidgen | tr '[:upper:]' '[:lower:]')" \
  --q-cli-disabled \
  --region eu-west-1 \
  --query '{SessionId:SessionId,TokenValue:TokenValue,StreamUrl:StreamUrl}' \
  --output json)" eu-west-1 StartSession

Et vous y êtes. Un shell complet sur une instance CloudShell, depuis votre terminal. Pas besoin de navigateur.

Le problème des credentials

Il y a un hic. Quand vous utilisez CloudShell depuis la Console, AWS injecte vos credentials automatiquement via un appel API PutCredentials. Celui-ci utilise votre token de session console (l'auth par cookie de votre connexion navigateur) pour alimenter le endpoint de métadonnées du conteneur en credentials temporaires.

Quand vous vous connectez par programme, ça ne se fait pas. Le endpoint de credentials du conteneur renvoie une erreur 500. Vous devez injecter les credentials vous-même :

# Exécutez localement, puis collez la sortie dans votre session CloudShell
aws configure export-credentials --profile my-profile --format env

Pas idéal, mais ça fonctionne.

Le cas d'usage bastion

C'est là que ça devient intéressant. Vous pouvez créer un environnement CloudShell attaché à un VPC :

aws cloudshell create-environment \
  --environment-name db-access \
  --vpc-config '{
    "VpcId": "vpc-abc123",
    "SubnetIds": ["subnet-private-1"],
    "SecurityGroupIds": ["sg-allowed-by-rds"]
  }' \
  --region eu-west-1

Mettez-le dans le même security group que celui autorisé par votre RDS, et soudain vous pouvez vous connecter à votre base de données directement depuis le shell :

mysql -h my-instance.xxx.eu-west-1.rds.amazonaws.com -u admin -p

Pas d'instance EC2 bastion à maintenir. Pas de clés SSH à gérer. Pas de coût horaire quand vous ne l'utilisez pas (CloudShell est gratuit). L'environnement se suspend après 20 minutes d'inactivité et vous pouvez le maintenir en vie avec aws cloudshell send-heart-beat.

Ce qui ne marche pas (et j'ai essayé..)

J'ai passé pas mal de temps à essayer de faire fonctionner CloudShell comme un vrai bastion de port-forwarding, pour pouvoir utiliser des outils locaux comme DBeaver contre un RDS distant à travers lui. Voici ce que j'ai trouvé :

Le port forwarding basé sur SSM ne fonctionne pas.

ECS, par exemple, enregistre les conteneurs comme cibles SSM. Son identifiant SSM n'est pas documenté mais une fois qu'on le connaît, ça marche bien, comme je l'ai décrit dans un précédent article. De cette façon vous pouvez lancer aws ssm start-session --document-name AWS-StartPortForwardingSessionToRemoteHost.
Les notebooks SageMaker ont un comportement similaire.

Les instances/conteneurs CloudShell ne semblent pas être enregistrés comme instances managées SSM. Ou s'ils le sont, c'est caché et à ce jour, personne chez AWS n'a divulgué le format de leur ID :) J'ai essayé toutes les combinaisons d'ID d'environnement, d'ID de session et de format de préfixe auxquelles j'ai pu penser. Aucune ne fonctionne.

Le port forwarding local à travers le PTY ne fonctionne pas non plus. La session est un terminal, pas un flux TCP brut. Vous ne pouvez pas faire passer des données binaires du protocole MySQL à travers. J'ai même essayé de mettre en place un relais ncat à l'intérieur de CloudShell et de tunneler à travers la session. Le relais fonctionne bien en interne, mais il n'y a aucun moyen de l'exposer comme un port TCP local sur votre machine.

Le hole punching UDP est théoriquement possible mais nécessite que le CloudShell ait accès à internet (NAT Gateway sur son subnet), et même là vous vous battez contre des problèmes de symétrie NAT des deux côtés. J'ai réussi à faire fonctionner STUN depuis CloudShell, mais le hole punch complet est fragile et impraticable pour un usage en production.

Alors à quoi ça sert ?

Honnêtement, à pas mal de choses :

Accès rapide à la base de données sans maintenir une instance EC2 bastion. Connectez-vous, exécutez vos requêtes, déconnectez-vous. Gratuit.
Automatisation. Vous pouvez scripter l'exécution de commandes sur CloudShell via Python + session-manager-plugin. Utile pour exécuter des choses à l'intérieur d'un VPC sans déployer une Lambda ou une tâche Fargate.
Débogage de connectivité réseau. Lancez un CloudShell dans une combinaison subnet/SG spécifique et testez ce qui peut atteindre quoi.
Transfert de fichiers (depuis les environnements publics). Les APIs get-file-upload-urls et get-file-download-urls vous donnent des URLs S3 présignées.

La limitation principale est que vous êtes limité à exécuter des commandes à l'intérieur du shell. Vous ne pouvez pas l'utiliser comme un tunnel transparent pour vos outils locaux. Pour ça, vous avez toujours besoin d'une instance EC2 avec l'agent SSM, ou d'une tâche ECS avec execute-command activé.

Essayez vous-même

J'ai publié le modèle et un script d'exemple ici : github.com/psantus/cloudshell-cli

L'installation se fait en une commande. Le tout est un seul fichier JSON qui apprend un nouveau service à votre AWS CLI. Rappelez-vous juste : c'est une API non documentée. AWS peut la modifier ou la casser à tout moment. Ne construisez rien de critique dessus.

Mais pour un accès VPC rapide depuis votre terminal ? C'est plutôt génial.

Générer des données structurées avec un LLM : quelques astuces pour plus de fiabilité

Paul SANTUS — Fri, 29 May 2026 12:41:31 +0000

Les LLMs sont excellents pour générer du texte. Ils sont mauvais pour générer des données structurées de manière fiable. Si vous avez déjà essayé de faire produire à un agent un objet JSON avec un schéma précis, vous connaissez le douloureux résultat : champs manquants, clés hallucinées, types incohérents, et des sorties qui cassent votre pipeline en aval.

Dépassant le stade du code de démo pour travailler sur de vraies applications IA en production, j'ai été confronté au problème et j'ai trouvé une approche qui fonctionne remarquablement bien pour une application IA que je développe : utiliser les outils comme le pattern Builder de la programmation orientée objet. Au lieu de demander au modèle de produire un blob JSON final, vous lui donnez des outils qui construisent la sortie de manière incrémentale - comme appeler des méthodes sur un objet. Le modèle ne voit ni ne produit jamais la structure finale directement. Il appelle simplement des outils, et la sortie structurée émerge comme un effet de bord.

C'est particulièrement important quand votre agent traite des documents volumineux (formulaires d'assurance, dossiers juridiques, dossiers médicaux) qui consomment la majeure partie de la fenêtre de contexte. Quand l'entrée est volumineuse et que la tâche comporte plusieurs étapes, vous ne pouvez pas vous permettre de réserver aussi de l'espace pour une sortie structurée massive à la fin. Le pattern accumulateur vous permet de compresser la conversation en cours de route sans perdre aucune des données structurées déjà collectées, car ces données vivent entièrement en dehors de la fenêtre de contexte.

Défis

"Génère-moi un gros JSON" : les soucis

L'approche naïve - demander au modèle de produire une structure JSON complète - échoue de manière quasi systématique lorsque le volume augmente :

Dérive de schéma. Le modèle oublie des champs obligatoires, en invente de nouveaux, ou change les types d'une exécution à l'autre. Un champ date peut être une chaîne une fois et un objet la suivante.
Tout-ou-rien. Si le modèle fait une seule erreur dans une sortie JSON de 200 lignes, l'ensemble est impossible à parser. Vous devez soit relancer toute la génération, soit écrire du code de correction fragile.
Pas de progrès incrémental. Quand un agent doit collecter des informations et produire une sortie structurée, lui demander de faire les deux en une seule passe signifie qu'il ne peut pas itérer. Il s'engage sur une structure avant d'avoir tous les faits.

Pourquoi `response_format` et les schémas de function-calling ne suffisent pas

Les modes de sortie structurée (comme response_format: json_schema d'OpenAI ou les schémas de résultats d'outils de Bedrock) aident avec la syntaxe - vous obtiendrez du JSON valide. Mais ils ne résolvent pas le problème sémantique. Le modèle doit toujours produire la structure entière en une seule passe, et il hallucine toujours du contenu pour remplir les champs obligatoires.

Un problème répandu

Toute équipe qui construit des agents autonomes ou semi-autonomes fait face à ce problème, pas seulement moi. Kiro CLI, le compagnon de développement agentique d'AWS, par exemple, a beaucoup galéré avec les grandes structures de données à son lancement.

Depuis, ses mainteneurs ont équipé son harnais de capacités JSON (manipulations jq, par exemple) et de multiples stratégies (utilisation extensive de grep, glob, tail..) pour éviter de remplir la fenêtre de contexte.

Ça fait quand même plaisir de savoir que je ne suis pas le seul à avoir galéré :)

Mes solutions

Voici quelques astuces que j'ai utilisées avec succès pour contrôler à la fois la sortie de l'agent et la fenêtre de contexte. Comme je ne prétends pas avoir toutes les recettes, n'hésitez pas à commenter les vôtres ou à me taguer dans vos propres posts :)

Utiliser les outils comme des Builder méthodes

L'idée centrale : définir des outils qui agissent comme des méthodes Builder en POO. Chaque appel d'outil ajoute un élément bien typé à un accumulateur. Le travail du modèle passe de "produis cette structure" à "appelle ces fonctions dans le bon ordre."

Voici le pattern - imaginez un agent qui traite des sinistres d'assurance en lisant des documents et en construisant une évaluation structurée :

from strands import tool

# L'accumulateur - c'est votre sortie structurée
claim_output = {
    "parties": [],
    "events": [],
    "damages": [],
    "evidence": [],
    "assessment": None,
}

def reset_output():
    claim_output["assessment"] = None
    for k in ["parties", "events", "damages", "evidence"]:
        claim_output[k] = []


@tool
def add_party(name: str, role: str, policy_id: str = "") -> str:
    """Enregistrer une partie impliquée dans le sinistre.

    Args:
        name: Nom complet de la personne ou de l'organisation.
        role: Un parmi : claimant, insured, witness, adjuster, third_party
        policy_id: Numéro de police si applicable.

    Returns:
        Confirmation avec les détails de la partie.
    """
    if role not in ("claimant", "insured", "witness", "adjuster", "third_party"):
        return f"Error: invalid role '{role}'. Must be one of: claimant, insured, witness, adjuster, third_party"

    claim_output["parties"].append({
        "name": name,
        "role": role,
        "policy_id": policy_id,
    })
    return f"Added {role}: {name}"


@tool
def add_event(description: str, date: str, location: str = "") -> str:
    """Enregistrer un événement chronologique pertinent pour le sinistre.

    Args:
        description: Ce qui s'est passé (1-3 phrases).
        date: Date au format ISO (AAAA-MM-JJ).
        location: Où cela s'est produit (optionnel).
    """
    claim_output["events"].append({
        "description": description,
        "date": date,
        "location": location,
    })
    return f"Recorded event on {date} ({len(claim_output['events'])} events total)"


@tool
def add_damage(item: str, amount: float, category: str, evidence_ref: str = "") -> str:
    """Enregistrer un poste de dommage avec le coût estimé.

    Args:
        item: Description de l'élément endommagé ou du coût.
        amount: Coût estimé en dollars.
        category: Un parmi : property, medical, liability, lost_income
        evidence_ref: Référence à une preuve justificative (optionnel).
    """
    if category not in ("property", "medical", "liability", "lost_income"):
        return f"Error: invalid category '{category}'."

    claim_output["damages"].append({
        "item": item,
        "amount": amount,
        "category": category,
        "evidence_ref": evidence_ref,
    })
    total = sum(d["amount"] for d in claim_output["damages"])
    return f"Added damage: {item} (${amount:.2f}). Running total: ${total:.2f}"

L'agent reçoit ces outils et un prompt système qui lui dit de traiter un sinistre. Au fur et à mesure qu'il lit les documents et découvre des informations, il appelle add_party, add_event et add_damage. La sortie structurée se construit de manière incrémentale.

Validation à la frontière

Chaque appel d'outil est un point de contrôle de validation. Vous pouvez rejeter les entrées invalides immédiatement :

@tool
def add_damage(item: str, amount: float, category: str, evidence_ref: str = "") -> str:
    if category not in ("property", "medical", "liability", "lost_income"):
        return f"Error: invalid category '{category}'."
    if amount <= 0:
        return f"Error: amount must be positive, got {amount}."
    if evidence_ref and evidence_ref not in [e["id"] for e in claim_output["evidence"]]:
        return f"Error: evidence '{evidence_ref}' not registered. Call add_evidence first."
    # ...

Le modèle reçoit un feedback instantané. S'il essaie de référencer une preuve qu'il n'a pas encore enregistrée, l'outil le lui dit. Le modèle se corrige au tour suivant. Comparez cela à la validation d'un blob JSON de 500 lignes après coup - à ce moment-là, le modèle est passé à autre chose et ne peut plus corriger ses erreurs dans le contexte.

Décorréler la phase de réflexion de la construction de la sortie

Un avantage clé : le même agent peut avoir des outils de lecture et des outils d'écriture. Les outils de lecture récupèrent et explorent les données. Les outils d'écriture construisent la sortie. Le modèle les entrelace naturellement :

agent = Agent(
    model=model,
    system_prompt=prompt,
    tools=[
        # Outils de lecture
        read_document,
        search_policy,
        get_weather_report,
        # Outils d'écriture (méthodes Builder)
        add_party,
        add_event,
        add_damage,
        add_evidence,
        set_assessment,
        # Suivi de progression
        mark_step_done,
    ],
)

# Un seul appel - l'agent lit les documents ET construit la sortie structurée
agent("Process this claim: " + claim_text)

# La sortie est prête
print(claim_output)

Le modèle lit un rapport de police, extrait une partie, lit une facture médicale, enregistre un poste de dommage, vérifie la police d'assurance, et ainsi de suite. Recherche et construction de la sortie sont entrelacées plutôt que séquentielles.

Suivi de progression et récupération

Parce que la sortie s'accumule de manière incrémentale, vous obtenez la récupération après crash gratuitement :

STEPS = [
    "1. Identify all parties",
    "2. Establish timeline of events",
    "3. Catalog damages with evidence",
    "4. Cross-reference policy coverage",
    "5. Produce assessment",
]
completed_steps: list[int] = []

@tool
def mark_step_done(step_number: int) -> str:
    """Marquer une étape de traitement comme terminée."""
    completed_steps.append(step_number)
    remaining = [s for i, s in enumerate(STEPS, 1) if i not in completed_steps]
    return f"Step {step_number} done. Remaining: {', '.join(remaining)}"

Si l'agent atteint une limite de fenêtre de contexte ou plante, vous avez déjà des résultats partiels - chaque partie identifiée, chaque événement enregistré, chaque poste de dommage catalogué jusqu'à ce point. Vous pouvez reprendre ou utiliser ce que vous avez.

Gestion du contexte par injection d'état

C'est là que ce pattern prend tout son sens. Quand votre agent ingère un document de 30 pages puis fait des dizaines d'appels d'outils pour récupérer des sources supplémentaires, la fenêtre de contexte se remplit vite. Dans une approche traditionnelle, vous perdriez votre sortie structurée en même temps que la conversation quand vous atteignez la limite. Mais parce que l'accumulateur vit dans la mémoire Python - pas dans l'historique des messages - vous pouvez compresser agressivement la conversation sans perdre un seul point de données.

Un gestionnaire de conversation personnalisé (une possibilité offerte, par exemple, par le SDK Strands Agents) remplace les anciens messages par un résumé d'état compact dérivé de l'accumulateur :

class ClaimConversationManager(ConversationManager):
    def apply_management(self, agent, **kwargs):
        messages = agent.messages
        if len(messages) <= 2:
            return

        # Garder le premier message + les 2 derniers messages
        # Remplacer tout le reste par un résumé d'état
        first_msg = messages[0]
        recent = messages[-2:]

        state = self._build_state_summary()
        state_msg = {
            "role": "user",
            "content": [{"text": f"[STATE]\n{state}\n\nContinue."}],
        }
        messages[:] = [first_msg, state_msg] + recent

    def _build_state_summary(self) -> str:
        """Résumer ce qui a été fait en utilisant l'état de l'accumulateur."""
        lines = []
        if claim_output["parties"]:
            parties = [f"{p['name']} ({p['role']})" for p in claim_output["parties"]]
            lines.append(f"Parties: {', '.join(parties)}")
        if claim_output["damages"]:
            total = sum(d["amount"] for d in claim_output["damages"])
            lines.append(f"Damages: {len(claim_output['damages'])} items, ${total:.2f} total")
        if claim_output["events"]:
            lines.append(f"Events: {len(claim_output['events'])} recorded")
        return "\n".join(lines)

Parce que la sortie structurée vit en Python (pas dans la conversation), la compression du contexte ne perd aucune donnée. Le modèle peut toujours voir ce qu'il a déjà produit en lisant le résumé d'état.

Bénéfices

Sûreté de typage sans coercition

Chaque outil a des paramètres typés imposés par le framework. Le modèle doit fournir une category parmi property, medical, liability, lost_income - non pas parce que vous parsez du JSON et vérifiez après coup, mais parce que la signature de l'outil l'exige. Les appels invalides sont rejetés avec des messages d'erreur clairs.

Composabilité

Les outils se composent naturellement. Vous pouvez ajouter de nouveaux champs de sortie en ajoutant de nouveaux outils sans modifier les existants. Vous voulez suivre les pièces justificatives ? Ajoutez un outil add_evidence. Vous voulez une recommandation finale ? Ajoutez un outil set_assessment. Le modèle découvre les nouvelles capacités via sa liste d'outils.

Testabilité

Chaque outil est une fonction pure (ou presque). Vous pouvez les tester unitairement de manière indépendante :

def test_add_damage_rejects_invalid_category():
    reset_output()
    result = add_damage(item="Roof repair", amount=5000, category="cosmetic")
    assert "Error" in result
    assert len(claim_output["damages"]) == 0

def test_add_damage_tracks_total():
    reset_output()
    add_damage(item="Roof repair", amount=5000, category="property")
    add_damage(item="Water damage", amount=2000, category="property")
    assert len(claim_output["damages"]) == 2
    assert sum(d["amount"] for d in claim_output["damages"]) == 7000

Schéma de sortie déterministe

Le schéma de sortie est défini par votre code Python, pas par l'interprétation du modèle d'un prompt. claim_output a toujours les mêmes clés avec les mêmes types. Les consommateurs en aval peuvent compter sur la structure de manière inconditionnelle.

Dégradation gracieuse

Si le modèle manque de contexte ou rencontre une erreur, vous avez tout ce qu'il a produit jusqu'à ce point. Vous pouvez même détecter une sortie vide et relancer avec un coup de pouce :

try:
    agent(claim_text)
except Exception:
    pass

if not claim_output["parties"] and not claim_output["events"]:
    agent("You haven't started processing. Begin by identifying the parties involved.")

Comportement naturel de l'agent

Le modèle n'a pas besoin de basculer entre "réfléchir" et "formater." Il réfléchit en appelant des outils. La sortie structurée est un sous-produit du travail de l'agent, pas un fardeau de formatage supplémentaire ajouté par-dessus.

Ce pattern - outils comme Builder, accumulateur comme sortie, validation à la frontière - est la manière la plus fiable que j'ai trouvée pour obtenir des données structurées d'un workflow agentique. Ça fonctionne parce que c'est aligné avec la façon dont les modèles à appels d'outils se comportent déjà : ils raisonnent, ils agissent, ils observent les résultats, et ils agissent à nouveau. Vous faites simplement en sorte que "agir" signifie "construire un morceau de la sortie."

LLMs suck at generating large, structured data. Tips on how to get your AI agent to do it reliably

Paul SANTUS — Fri, 29 May 2026 12:06:19 +0000

LLMs are great at generating text. They're terrible at generating structured data reliably. If you've ever tried to get an agent to produce a JSON object with a specific schema, you know the pain: missing fields, hallucinated keys, inconsistent types, and outputs that break your downstream pipeline.

As I got past toy examples and labs to work on real, production-grade AI apps, I faced the problem and found an approach that works remarkably well for an AI app I'm building: use tools like object-oriented programming Builder pattern. Instead of asking the model to produce a final JSON blob, you give it tools that incrementally build the output - like calling methods on an object. The model never sees or produces the final structure directly. It just calls functions, and the structured output emerges as a side effect.

This matters especially when your agent processes large documents (like insurance forms, legal filings, medical records) that eat up most of the context window. When the input is big and the task is multi-step, you can't afford to also reserve space for a massive structured output at the end. The accumulator pattern lets you compress the conversation mid-flight without losing any of the structured data you've already collected, because that data lives outside the token window entirely.

Challenges

The "generate JSON" problem

The naive approach - asking a model to output a complete JSON structure - fails in predictable ways:

Schema drift. The model forgets required fields, invents new ones, or changes types between runs. A date field might be a string one time and an object the next.
All-or-nothing failure. If the model makes one mistake in a 200-line JSON output, the entire thing is unparseable. You either retry the whole generation or write brittle fixup code.
No incremental progress. If the model hits a context limit or stops mid-generation, you lose everything. There's no partial result to recover from.
Hallucination in structure. Models are more likely to hallucinate when producing structured output in one shot. They fill in fields they're uncertain about rather than leaving them empty, because the structure demands completeness.
Coupling research and output. When an agent needs to gather information and produce structured output, asking it to do both in one pass means it can't iterate. It commits to a structure before it has all the facts.

Why `response_format` and function-calling schemas aren't enough

Structured output modes (like OpenAI's response_format: json_schema or Bedrock's tool result schemas) help with syntax - you'll get valid JSON. But they don't solve the semantic problem. The model still has to produce the entire structure in one shot, and it still hallucinates content to fill required fields.

A wide-spread issue

Any team building autonomous or semi-autonomous agents face this, not just me. Kiro CLI, AWS' agentic dev companion, for instance, struggled hard with large data structures when first launched.

Since then, its maintainers have equipped its harness with JSON capabilities (jq manipulations, for instance) and multiples strategies (extensive use of grep, glob, tail..) to avoid filling the context window.

Still, happy to know I'm not alone in facing this :)

My solutions

Here are a few tricks I have used successfully to control both agent output and context window. As I don't claim to have all the recipes, don't hesitate to comment your own or tag my in your own posts :)

Tools as Builder methods

The core idea: define tools that act like OOP builder methods. Each tool call adds one well-typed element to an accumulator. The model's job shifts from "produce this structure" to "call these functions in the right order."

Here's the pattern - imagine an agent that processes insurance claims by reading documents and building a structured claim assessment:

from strands import tool

# The accumulator - this is your structured output
claim_output = {
    "parties": [],
    "events": [],
    "damages": [],
    "evidence": [],
    "assessment": None,
}

def reset_output():
    claim_output["assessment"] = None
    for k in ["parties", "events", "damages", "evidence"]:
        claim_output[k] = []


@tool
def add_party(name: str, role: str, policy_id: str = "") -> str:
    """Register a party involved in the claim.

    Args:
        name: Full name of the person or organization.
        role: One of: claimant, insured, witness, adjuster, third_party
        policy_id: Policy number if applicable.

    Returns:
        Confirmation with party details.
    """
    if role not in ("claimant", "insured", "witness", "adjuster", "third_party"):
        return f"Error: invalid role '{role}'. Must be one of: claimant, insured, witness, adjuster, third_party"

    claim_output["parties"].append({
        "name": name,
        "role": role,
        "policy_id": policy_id,
    })
    return f"Added {role}: {name}"


@tool
def add_event(description: str, date: str, location: str = "") -> str:
    """Record a chronological event relevant to the claim.

    Args:
        description: What happened (1-3 sentences).
        date: ISO date string (YYYY-MM-DD).
        location: Where it happened (optional).
    """
    claim_output["events"].append({
        "description": description,
        "date": date,
        "location": location,
    })
    return f"Recorded event on {date} ({len(claim_output['events'])} events total)"


@tool
def add_damage(item: str, amount: float, category: str, evidence_ref: str = "") -> str:
    """Register a damage item with estimated cost.

    Args:
        item: Description of the damaged item or cost.
        amount: Estimated cost in dollars.
        category: One of: property, medical, liability, lost_income
        evidence_ref: Reference to supporting evidence (optional).
    """
    if category not in ("property", "medical", "liability", "lost_income"):
        return f"Error: invalid category '{category}'."

    claim_output["damages"].append({
        "item": item,
        "amount": amount,
        "category": category,
        "evidence_ref": evidence_ref,
    })
    total = sum(d["amount"] for d in claim_output["damages"])
    return f"Added damage: {item} (${amount:.2f}). Running total: ${total:.2f}"

The agent is given these tools and a system prompt that tells it to process a claim. As it reads documents and discovers information, it calls add_party, add_event, and add_damage. The structured output builds up incrementally.

Validation at the boundary

Each tool call is a validation checkpoint. You can reject bad input immediately:

@tool
def add_damage(item: str, amount: float, category: str, evidence_ref: str = "") -> str:
    if category not in ("property", "medical", "liability", "lost_income"):
        return f"Error: invalid category '{category}'."
    if amount <= 0:
        return f"Error: amount must be positive, got {amount}."
    if evidence_ref and evidence_ref not in [e["id"] for e in claim_output["evidence"]]:
        return f"Error: evidence '{evidence_ref}' not registered. Call add_evidence first."
    # ...

The model gets instant feedback. If it tries to reference evidence it hasn't registered yet, the tool tells it. The model self-corrects on the next turn. Compare this to validating a 500-line JSON blob after the fact - by then, the model has moved on and can't fix its mistakes in context.

Separating research from output construction

A key benefit: the same agent can have reading tools and writing tools. Reading tools fetch and explore data. Writing tools construct the output. The model interleaves them naturally:

agent = Agent(
    model=model,
    system_prompt=prompt,
    tools=[
        # Reading tools
        read_document,
        search_policy,
        get_weather_report,
        # Writing tools (builder methods)
        add_party,
        add_event,
        add_damage,
        add_evidence,
        set_assessment,
        # Progress tracking
        mark_step_done,
    ],
)

# One call - the agent reads documents AND builds structured output
agent("Process this claim: " + claim_text)

# Output is ready
print(claim_output)

The model reads a police report, extracts a party, reads a medical bill, registers a damage item, cross-references the policy, and so on. Research and output construction are interleaved rather than sequential.

Progress tracking and recovery

Because output accumulates incrementally, you get crash recovery for free:

STEPS = [
    "1. Identify all parties",
    "2. Establish timeline of events",
    "3. Catalog damages with evidence",
    "4. Cross-reference policy coverage",
    "5. Produce assessment",
]
completed_steps: list[int] = []

@tool
def mark_step_done(step_number: int) -> str:
    """Mark a processing step as completed."""
    completed_steps.append(step_number)
    remaining = [s for i, s in enumerate(STEPS, 1) if i not in completed_steps]
    return f"Step {step_number} done. Remaining: {', '.join(remaining)}"

If the agent hits a context window limit or errors out, you already have partial results - every party identified, every event recorded, every damage item cataloged up to that point. You can resume or use what you have.

Context management with state injection

Here's where this pattern really pays off. When your agent ingests a 30-page document and then makes dozens of tool calls to fetch additional sources, the context window fills up fast. In a traditional approach, you'd lose your structured output along with the conversation when you hit the limit. But because the accumulator lives in Python memory - not in the message history - you can aggressively compress the conversation without losing a single data point.

A custom conversation manager (a possibility offered, for instance, by the Strands Agents SDK) replaces old messages with a compact state summary derived from the accumulator:

class ClaimConversationManager(ConversationManager):
    def apply_management(self, agent, **kwargs):
        messages = agent.messages
        if len(messages) <= 2:
            return

        # Keep first message + last 2 messages
        # Replace everything in between with a state summary
        first_msg = messages[0]
        recent = messages[-2:]

        state = self._build_state_summary()
        state_msg = {
            "role": "user",
            "content": [{"text": f"[STATE]\n{state}\n\nContinue."}],
        }
        messages[:] = [first_msg, state_msg] + recent

    def _build_state_summary(self) -> str:
        """Summarize what's been done using the accumulator state."""
        lines = []
        if claim_output["parties"]:
            parties = [f"{p['name']} ({p['role']})" for p in claim_output["parties"]]
            lines.append(f"Parties: {', '.join(parties)}")
        if claim_output["damages"]:
            total = sum(d["amount"] for d in claim_output["damages"])
            lines.append(f"Damages: {len(claim_output['damages'])} items, ${total:.2f} total")
        if claim_output["events"]:
            lines.append(f"Events: {len(claim_output['events'])} recorded")
        return "\n".join(lines)

Because the structured output lives in Python (not in the conversation), context compression doesn't lose any data. The model can always see what it's already produced by reading the state summary.

Benefits

Type safety without type coercion

Each tool has typed parameters enforced by the framework. The model must provide a category that's one of property, medical, liability, lost_income - not because you're parsing JSON and checking after the fact, but because the tool signature demands it. Invalid calls get rejected with clear error messages.

Composability

Tools compose naturally. You can add new output fields by adding new tools without changing existing ones. Want to track evidence attachments? Add an add_evidence tool. Want a final recommendation? Add a set_assessment tool. The model discovers new capabilities through its tool list.

Testability

Each tool is a pure function (or close to it). You can unit test them independently:

def test_add_damage_rejects_invalid_category():
    reset_output()
    result = add_damage(item="Roof repair", amount=5000, category="cosmetic")
    assert "Error" in result
    assert len(claim_output["damages"]) == 0

def test_add_damage_tracks_total():
    reset_output()
    add_damage(item="Roof repair", amount=5000, category="property")
    add_damage(item="Water damage", amount=2000, category="property")
    assert len(claim_output["damages"]) == 2
    assert sum(d["amount"] for d in claim_output["damages"]) == 7000

Deterministic output schema

The output schema is defined by your Python code, not by the model's interpretation of a prompt. claim_output always has the same keys with the same types. Downstream consumers can rely on the structure unconditionally.

Graceful degradation

If the model runs out of context or hits an error, you have everything it produced up to that point. You can even detect empty output and retry with a nudge:

try:
    agent(claim_text)
except Exception:
    pass

if not claim_output["parties"] and not claim_output["events"]:
    agent("You haven't started processing. Begin by identifying the parties involved.")

Natural agent behavior

The model doesn't have to context-switch between "thinking" and "formatting." It thinks by calling tools. The structured output is a byproduct of the agent doing its job, not an additional formatting burden layered on top.

This pattern - tools as Builder, accumulator as output, validation at the boundary - has been the most reliable way I've found to get structured data out of an agentic workflow. It works because it aligns with how tool-calling models already behave: they reason, they act, they observe results, and they act again. You're just making "act" mean "build one piece of the output."

Hack your AWS CLI to add CloudShell support and turn your terminal into a bastion

Paul SANTUS — Thu, 28 May 2026 10:10:55 +0000

I've been using AWS CloudShell from the Console for a while. It's convenient: a pre-authenticated shell in your browser, right there in the AWS Console. But I always wondered: why can't I use it from my terminal? Why is there no aws cloudshell command?

Turns out, you can make it happen. The API exists, it's just not public. And once you have CLI access to CloudShell, you can do interesting things with it, like using a VPC-attached CloudShell as a bastion to reach your private RDS instances.

Checkout the companion repository as you read through this blog post.

CloudShell: an undocumented API

AWS CloudShell has no official SDK or CLI support. But the Console has to talk to something, right? By looking at what the browser does when you open CloudShell, you can reverse-engineer the API.

Thankfully, Jérôme Guyon already did that work and published a boto3-compatible service model. His work made this whole thing possible.

The API is straightforward: create environments, start/stop them, create sessions, upload/download files. The session mechanism uses SSM's WebSocket protocol under the hood, which means session-manager-plugin (the same binary that powers aws ssm start-session) can connect to CloudShell sessions.

Teaching the AWS CLI a new trick

The AWS CLI has a little-known feature: aws configure add-model. Give it a JSON service model, and suddenly the CLI knows about a new service. AWS uses this internally for private previews.

(The boto3 model from Jérôme's repo just needs a "version": "2.0" field added at the top level to become CLI-compatible.)

Run:

aws configure add-model \
  --service-model file://cloudshell-cli-model.json \
  --service-name cloudshell

That's it. Now I have aws cloudshell with tab completion and everything:

$ aws cloudshell help

AVAILABLE COMMANDS
       create-environment
       create-session
       delete-environment
       describe-environments
       get-environment-status
       start-environment
       stop-environment
       ...

Connecting to CloudShell from the terminal

The workflow is simple:

# Create or find an environment
aws cloudshell create-environment --region eu-west-1

# Wait for it to be RUNNING
aws cloudshell get-environment-status --environment-id <ID> --region eu-west-1

# Create a session and connect
session-manager-plugin "$(aws cloudshell create-session \
  --environment-id <ID> \
  --session-type TMUX \
  --tab-id "$(uuidgen | tr '[:upper:]' '[:lower:]')" \
  --q-cli-disabled \
  --region eu-west-1 \
  --query '{SessionId:SessionId,TokenValue:TokenValue,StreamUrl:StreamUrl}' \
  --output json)" eu-west-1 StartSession

And you're in. A full shell on a CloudShell instance, from your terminal. No browser needed.

The credentials problem

There's a catch. When you use CloudShell from the Console, AWS injects your credentials automatically via a PutCredentials API call. This uses your console session token (the cookie-based auth from your browser login) to feed temporary credentials into the container's metadata endpoint.

When you connect programmatically, that doesn't happen. The container's credential endpoint returns a 500 error. You need to inject credentials yourself:

# Run locally, then paste the output into your CloudShell session
aws configure export-credentials --profile my-profile --format env

Not ideal, but it works.

The bastion use case

Here's where it gets interesting. You can create a VPC-attached CloudShell environment:

aws cloudshell create-environment \
  --environment-name db-access \
  --vpc-config '{
    "VpcId": "vpc-abc123",
    "SubnetIds": ["subnet-private-1"],
    "SecurityGroupIds": ["sg-allowed-by-rds"]
  }' \
  --region eu-west-1

Put it in the same security group that your RDS allows, and suddenly you can connect to your database directly from the shell:

mysql -h my-instance.xxx.eu-west-1.rds.amazonaws.com -u admin -p

No EC2 bastion instance to maintain. No SSH keys to manage. No hourly cost when you're not using it (CloudShell is free). The environment suspends after 20 minutes of inactivity and you can keep it alive with aws cloudshell send-heart-beat.

What doesn't work (and I tried..)

I spent a fair amount of time trying to make CloudShell work as a proper port-forwarding bastion, so you could use local tools like DBeaver against a remote RDS through it. Here's what I found:

SSM-based port forwarding doesn't work.

ECS, for instance, registers containers as SSM targets. Its SSM identifier is undocumented but once you know it, it works well, as I have described in a previous blog post. This way you can run aws ssm start-session --document-name AWS-StartPortForwardingSessionToRemoteHost.
SageMaker notebooks have kinda the same behaviour.

CloudShell instances/containers seem not to be registered as SSM managed instances. Or if they are, it's hidden and as of today, no one at AWS leaked their ID format :) I tried every combination of environment ID, session ID, and prefix format I could think of. None of them work.

Local port forwarding through the PTY doesn't work either. The session is a terminal, not a raw TCP stream. You can't pipe binary MySQL protocol data through it. I even tried setting up an ncat relay inside CloudShell and tunneling through the session. The relay works fine internally, but there's no way to expose it as a local TCP port on your machine.

UDP hole punching is theoretically possible but requires the CloudShell to have internet access (NAT Gateway on its subnet), and even then you're fighting NAT symmetry issues on both ends. I got STUN working from CloudShell, but the full hole punch is fragile and impractical for production use.

So what is it good for?

Honestly, quite a lot:

Quick database access without maintaining a bastion EC2 instance. Connect, run your queries, disconnect. Free.
Automation. You can script command execution on CloudShell via Python + session-manager-plugin. Useful for running things inside a VPC without deploying a Lambda or Fargate task.
Debugging network connectivity. Spin up a CloudShell in a specific subnet/SG combination and test what can reach what.
File transfer (from public environments). The get-file-upload-urls and get-file-download-urls APIs give you presigned S3 URLs.

The main limitation is that you're stuck running commands inside the shell. You can't use it as a transparent tunnel for local tools. For that, you still need an EC2 instance with SSM agent, or an ECS task with execute-command enabled.

Try it yourself

I published the model and a sample script here: github.com/psantus/cloudshell-cli

Installation is one command. The whole thing is a single JSON file that teaches your AWS CLI a new service. Just remember: this is an undocumented API. AWS can change or break it at any time. Don't build anything mission-critical on top of it.

But for quick VPC access from your terminal? It's pretty great.

Ne lâchez pas la bride à votre LLM

Paul SANTUS — Fri, 15 May 2026 13:27:27 +0000

Shannon l'avait prédit : un bon prompt ne remplacera jamais une boucle de feedback.

Une idée séduisante qui circule : donnez un bon prompt à un LLM, et il vous génère une application complète. Simple, rapide, magique. Vibe !

Sauf que c'est physiquement impossible. Claude Shannon l'expliquait dès 1948.

Le problème informationnel

La théorie de l'information nous enseigne un principe fondamental : on ne peut pas créer de l'information à partir de rien. Un canal de communication ne peut pas produire en sortie plus d'information qu'il n'en reçoit en entrée.

Or, regardons ce qu'on demande :

En entrée : un prompt de quelques lignes. Quelques centaines de bits d'information utile. Des intentions vagues, des contraintes implicites, des choix de design non formulés.
En sortie attendue : une application complète. Des milliers de décisions d'architecture, de design, d'UX, de gestion d'erreurs, de cas limites. Des millions de bits d'information.

Ce que le LLM apporte (et ce qu'il n'apporte pas)

Soyons honnêtes : le LLM ajoute bien de l'information. Il ne tire pas à pile ou face. Il puise dans un immense corpus d'entraînement pour combler les vides ; ses milliards de paramètres enrichissent vos 300 tokens péniblement accouchés.

Mais de quelle information s'agit-il, exactement ?

Du boilerplate. De la connaissance formelle. Les patterns classiques d'une API REST. La façon idiomatique de connecter une base de données en Python. La structure standard d'un composant React. Les conventions de nommage. Les imports habituels.

Tout ce qui relève du "comment fait-on cela généralement ?" est couvert, et c'est précieux. C'est ce qui rend le LLM si bluffant sur les démos : il produit du code qui ressemble à une vraie application, parce que la coquille formelle est correcte.

Mais votre logique métier ? Les compromis d'architecture spécifiques à votre contexte ? Le comportement exact attendu dans ce cas limite que seul votre utilisateur connaît ? Cette info n'est dans aucun corpus. C'est dans votre tête, et nulle part ailleurs.

Le LLM fournit le squelette. Vous fournissez l'âme. En termes formels : la complexité de Kolmogorov de votre application (la quantité minimale d'information pour la décrire entièrement) est bien supérieure à celle de votre prompt. Le LLM comble l'écart avec de l'information générique. Mais l'information spécifique à votre contexte est incompressible. Seul vous pouvez la fournir.

Une expérience de pensée.

Prenez une application qui fonctionne. Demandez au meilleur LLM du monde : "écris-moi le prompt parfait pour générer cette application à l'identique." Puis soumettez ce prompt à ce même LLM. Vous n'obtiendrez pas la même application. Jamais. Vous pouvez recommencer une fois, deux fois, cent fois : cent résultats différents, aucun identique à l'original.

Un prompt est à une application ce qu'un hash SHA1 est à un fichier : une réduction irréversible (un "hash"). Personne ne s'attend à reconstruire un fichier à partir de son empreinte. Pourquoi s'attendrait-on à reconstruire une application à partir de son prompt ?

Comme une impression de déjà-vu

Cette situation n'est pas nouvelle. En fait, le monde du logiciel l'a vécue pendant des décennies.

Les projets "effet tunnel" des années 2000 fonctionnaient exactement sur ce principe : on rédigeait un cahier des charges (l'équivalent d'un gros prompt), on l'envoyait à une équipe de développement (l'équivalent d'un LLM), et on attendait le résultat final des mois plus tard.

Le résultat ? Systématiquement décevant. Et pourtant, ces spécifications faisaient des centaines de pages, infiniment plus détaillées qu'un prompt. Des équipes entières passaient des mois à les rédiger. Malgré cela, le produit livré ne correspondait jamais aux attentes réelles.

Pourquoi ? Parce que même des centaines de pages de spécifications ne contiennent pas assez d'information pour décrire un logiciel complet. Les vrais besoins émergent à l'usage. Les bonnes décisions se prennent face au concret, pas dans l'abstrait.

L'agilité avait la réponse

L'industrie a mis quinze ans à comprendre et à adopter la solution : raccourcir la boucle de feedback.

L'agilité ne dit pas "ne spécifiez pas". Elle dit : "spécifiez peu, livrez vite, observez, ajustez, recommencez". L'information manquante dans la spécification initiale est injectée itération après itération, par le retour du réel.

C'est exactement le mécanisme qui compense le déficit informationnel de Shannon : chaque itération est un nouveau message sur le canal, qui apporte l'information que le message précédent ne contenait pas.

Avec l'IA, le piège est le même, en pire

Le LLM accélère spectaculairement la génération de code. C'est indéniable. Mais cette vitesse crée une illusion dangereuse : puisque le code sort vite, on croit que le produit avance vite.

Or le travail produit (comprendre le besoin, valider les choix, vérifier l'adéquation) reste incompressible. Il nécessite un humain dans la boucle, des retours fréquents, des corrections de trajectoire.

Générer 2000 lignes de code en 30 secondes pour découvrir après coup que l'architecture est inadaptée, c'est du waterfall à la vitesse de la lumière. C'est pire que l'effet tunnel classique parce que, le coût perçu étant faible, on recommence sans remettre en question l'approche.

L'illusion de la fenêtre de contexte

"Mais les LLM ont maintenant des fenêtres de contexte énormes !" Oui. Et ça aggrave le problème.

Une grande fenêtre de contexte donne l'illusion que le LLM peut traiter un sujet en profondeur, tout seul, en accumulant du raisonnement interne. En pratique, sans apport externe, il s'enferme dans sa propre "intuition". Il tourne en boucle. Il reformule. Il essaie des variantes de la même mauvaise idée. Il crame des tokens.

On a tous vu passer sur LinkedIn ces posts : "Claude a brûlé mon quota mensuel de tokens en 2h." Ce n'est pas un bug. C'est Shannon qui se manifeste : le LLM n'a pas reçu d'information nouvelle, donc il ne peut pas converger. Il génère du volume, pas de la valeur.

J'en ai fait l'expérience à répétition : un LLM coincé dans une spirale infernale depuis vingt minutes, accumulant des tentatives de plus en plus alambiquées. La solution ? Réduire le contexte (une simple commande /compact dans mon outil favori, Kiro CLI), puis injecter une minuscule correction humaine : "essaie plutôt ça" ou "je pense que X est l'origine du problème". Cinq mots. Et le LLM repart immédiatement dans la bonne direction.

Ces cinq mots contiennent plus d'information utile que les 50 000 tokens que le LLM venait de se générer à lui-même. Parce que c'est de l'information externe, qui brise la circularité. C'est exactement le signal sur le canal que Shannon décrit : sans nouveau message de l'émetteur, le récepteur ne peut pas corriger sa trajectoire.

La bonne posture

Ne lâchez pas la bride à votre LLM. Travaillez avec lui comme vous travailleriez en agile.

La cybernétique appelle ça la loi de la variété requise (Ashby, 1956) : pour piloter un système complexe, votre mécanisme de contrôle doit avoir au moins autant de variété que le système lui-même. Une application a une variété énorme (tous les comportements, états, cas limites possibles). Un seul prompt est une seule action de contrôle. Une action ne peut pas contraindre un système à millions d'états. Il en faut beaucoup, appliquées séquentiellement. Autrement dit : des itérations.

Itérations courtes : demandez un petit morceau, validez-le, puis passez au suivant. (Ce billet, par exemple ^^ : quelques idées en deux phrases, expansées par une IA, puis au moins cinq ou six itérations de feedback humain pour arriver à ce que vous lisez. CQFD.)
Feedback constant : relisez, testez, corrigez la trajectoire à chaque étape.
Décisions explicites : chaque choix de design que vous ne formulez pas est un choix que le LLM fera à votre place. Probablement pas comme vous l'auriez voulu.
Incréments fonctionnels : préférez un résultat partiel qui marche à un résultat complet qui ne correspond à rien.

Itérez !

Shannon nous le dit depuis 78 ans : l'information ne se crée pas spontanément. Un prompt court ne peut pas produire une application complète qui corresponde à vos besoins. Le LLM comble le vide avec ce qu'il connaît (le boilerplate, les patterns, les conventions), mais pas avec ce qu'il ne peut pas connaître : votre intention précise.

L'écart informationnel doit être comblé quelque part, et ce quelque part, c'est la boucle de rétroaction entre vous et votre outil.

L'IA accélère la frappe, pas la réflexion. Elle amplifie votre capacité d'exécution, pas votre capacité de décision. Gardez la main. Itérez. Ne confondez pas vitesse de génération et vitesse de création de valeur.

Le vrai superpouvoir, ce n'est pas le prompt parfait. C'est la prise de décision continue.

Remplacez AWS Transfer Family SFTP par S3 Files + Atmoz SFTP

Paul SANTUS — Wed, 08 Apr 2026 08:37:49 +0000

AWS vient de lancer l'une des fonctionnalités de stockage les plus attendues : S3 Files. S3 Files place une interface de système de fichiers compatible EFS directement devant vos buckets S3. Quand j'ai entendu parler de cette fonctionnalité (dans le cadre du programme Community Builders) j'ai tout de suite pensé au cas d'usage du SFTP sur AWS.

Si vous payez actuellement AWS Transfer Family pour donner à vos partenaires un accès SFTP à S3, lisez attentivement ce qui suit. Il existe désormais une alternative nettement moins chère et plus puissante.

Qu'est-ce que S3 Files ?

S3 Files crée un système de fichiers NFS haute performance adossé à un bucket S3. Voyez-le comme une couche EFS qui lit et écrit directement dans les objets S3, avec une synchronisation bidirectionnelle automatique. Tout fichier écrit via le système de fichiers apparaît comme un objet S3, et tout objet uploadé dans S3 devient visible via le système de fichiers.

Les propriétés clés :

Latence sub-milliseconde pour les opérations fichier
Synchronisation automatique entre le système de fichiers et le bucket S3 (via EventBridge sous le capot)
Montable sur ECS Fargate, ECS Managed Instances, EKS et EC2
Protocole NFS standard — pas de client spécial nécessaire côté compute (ECS/EKS le gèrent nativement)
Points d'accès avec contrôle d'identité POSIX (uid/gid)
S3 Versioning requis et exploité pour la cohérence

Le problème avec AWS Transfer Family

AWS Transfer Family est la solution "officielle" pour exposer des endpoints SFTP adossés à S3. Ça fonctionne, mais avec des inconvénients sérieux :

C'est cher

Transfer Family facture 0,30 $/heure rien que pour l'endpoint — soit ~216 $/mois avant même de transférer un seul octet. Ajoutez les coûts de transfert de données par-dessus. Pour un service que beaucoup d'équipes utilisent pour quelques dépôts de fichiers quotidiens, c'est difficile à justifier.

C'est une boîte noire

Vous obtenez un endpoint SFTP, mais vous ne contrôlez pas le serveur. L'authentification personnalisée nécessite des hooks Lambda. Le logging est limité. Vous ne pouvez pas vous connecter en SSH pour débugger. Vous ne pouvez pas personnaliser le comportement du serveur SFTP, ajouter des scripts de pré/post-traitement, ou exécuter quoi que ce soit à côté.

La nouvelle architecture : atmoz/sftp + S3 Files sur ECS Fargate

Voici ce que nous allons mettre en place :

Les composants :

Bucket S3 avec versioning activé (requis par S3 Files)
Système de fichiers S3 Files pointant vers le bucket, avec des mount targets dans votre VPC
Volume EFS pour les clés SSH persistantes (empreinte stable entre les redémarrages et le scaling)
Service ECS Fargate exécutant atmoz/sftp avec le volume S3 Files monté sur /home
Network Load Balancer exposant le port 22
Enregistrement DNS pour sftp.votredomaine.com (optionnel)

Les fichiers uploadés via SFTP atterrissent sur le montage S3 Files → apparaissent dans S3 en quelques secondes → déclenchent les notifications S3 pour le traitement en aval.

Comparaison des coûts

Composant	Transfer Family	S3 Files + Fargate
Coût de base	0,30 $/h (~216 $/mois)	NLB : ~16 $/mois
Compute	Inclus	Fargate 0.25 vCPU / 512 Mo : ~9 $/mois
Stockage	Tarification S3	Tarification S3 (identique)
Transfert de données	0,04 $/Go via SFTP	Tarification NLB standard
Minimum mensuel	~216 $	~25 $

C'est environ 8 fois moins cher au niveau de base. Pour les cas d'usage SFTP à trafic faible à moyen (c'est-à-dire la majorité), les économies sont significatives.

Pourquoi c'est mieux que du SFTP sur EFS

Avant S3 Files, l'approche DIY classique consistait à monter EFS sur Fargate et faire tourner atmoz/sftp. C'est exactement ce que nous faisions. Ça marchait, mais avec une limitation fondamentale : vos fichiers vivaient dans EFS, pas dans S3.

Ça signifiait :

Pas de notifications S3 à l'arrivée des fichiers
Pas de politiques de cycle de vie S3
Pas de réplication cross-region S3
Pas d'accès direct aux fichiers via l'API S3
Tarification EFS (0,30 $/Go pour Standard) vs S3 (0,023 $/Go)
Stratégie de backup séparée nécessaire

Avec S3 Files, les données vivent dans S3. Vous bénéficiez de tout l'écosystème S3 — notifications, règles de cycle de vie, réplication, analytics, tiering Glacier — tout en ayant un système de fichiers montable pour votre serveur SFTP.

Traitement événementiel des fichiers

Transfer Family et notre approche S3 Files écrivent tous deux dans S3, donc vous obtenez les mêmes capacités événementielles dans les deux cas :

Notifications S3 → SQS/SNS/Lambda pour un traitement immédiat à l'arrivée d'un fichier
Notifications S3 → EventBridge pour des règles de routage complexes
S3 Inventory pour l'audit
S3 Object Lock pour la conformité
S3 Replication pour répliquer les fichiers uploadés vers une autre région ou un autre compte

La différence n'est pas dans les fonctionnalités — c'est dans le coût. Vous obtenez exactement le même pipeline événementiel S3 pour ~25 $/mois au lieu de ~216 $/mois.

L'implémentation Terraform

Comme aws_s3files_file_system n'est pas encore dans le provider Terraform AWS (PR #47325 ouverte et priorisée), nous gérons les ressources S3 Files via terraform_data avec des provisioners local-exec appelant l'AWS CLI.

Les ressources clés :

# Système de fichiers S3 Files — créé via AWS CLI
resource "terraform_data" "s3files_file_system" {
  provisioner "local-exec" {
    command = <<-EOT
      aws s3files create-file-system \
        --bucket "$BUCKET_ARN" \
        --role-arn "$ROLE_ARN" \
        --accept-bucket-warning \
        --region "$REGION"
    EOT
  }
}

# Mount targets dans chaque sous-réseau privé
resource "terraform_data" "s3files_mount_targets" {
  for_each = toset(var.private_subnet_ids)
  provisioner "local-exec" {
    command = <<-EOT
      aws s3files create-mount-target \
        --file-system-id "$FS_ID" \
        --subnet-id "${each.value}" \
        --security-groups "$SG_ID"
    EOT
  }
}

# La task definition ECS utilise s3filesVolumeConfiguration
volume = {
  sftp-home = {
    s3files_volume_configuration = {
      file_system_arn = local.s3files_fs_arn
      root_directory  = "/"
    }
  }
}

Le code Terraform complet est disponible en tant que module Terraform. Le provider Terraform AWS ne supporte pas encore aws_s3files_file_system (PR #47325 ouverte et priorisée), donc les ressources S3 Files sont actuellement gérées via terraform_data + AWS CLI. Je m'engage à mettre à jour ce module pour utiliser les ressources Terraform natives dès que le provider intégrera le support S3 Files.

Configuration IAM

Deux rôles IAM sont nécessaires :

Rôle de service S3 Files — assumé par elasticfilesystem.amazonaws.com pour synchroniser entre le système de fichiers et le bucket S3. Nécessite un accès S3 en lecture/écriture sur le bucket + des permissions EventBridge pour la détection des changements.
Rôle de tâche ECS — nécessite s3files:ClientMount, s3files:ClientWrite, et s3:GetObject/s3:ListBucket sur le bucket pour des lectures optimisées.

Quand Transfer Family reste pertinent

Pour être honnête, Transfer Family n'est pas mort pour tous les cas d'usage :

Gestion managée des clés SFTP et des utilisateurs — Transfer Family intègre nativement des fournisseurs d'identité (AD, authentification Lambda custom). Avec atmoz/sftp, vous gérez les utilisateurs via la configuration.
Support du protocole AS2 — si vous avez besoin d'AS2, Transfer Family reste la seule option managée.
FTPS — Transfer Family supporte FTPS nativement.
Tolérance zéro aux opérations — si vous ne pouvez vraiment pas gérer un conteneur, Transfer Family est entièrement managé.

Mais pour la grande majorité des cas d'usage SFTP — des partenaires qui déposent des fichiers à traiter — l'approche S3 Files est moins chère, plus flexible, et offre une meilleure observabilité.

Pour démarrer

Prérequis : Les commandes aws s3files nécessitent AWS CLI v2.34.26 ou ultérieur. Vous avez également besoin de jq (utilisé par les scripts des provisioners Terraform). Mettez à jour la CLI avec brew upgrade awscli ou consultez le guide d'installation AWS CLI.

Créer un bucket S3 avec le versioning activé
Créer un rôle IAM pour S3 Files avec les politiques de confiance et de permissions requises
Créer un système de fichiers S3 Files via la console ou aws s3files create-file-system
Créer des mount targets dans vos sous-réseaux VPC
Créer un EFS pour les clés SSH persistantes
Déployer un service ECS Fargate avec atmoz/sftp, en montant S3 Files sur /home et EFS sur /etc/ssh/
Placer un NLB devant, pointer votre DNS dessus
Configurer les notifications S3 sur le bucket pour le traitement en aval

Ou utilisez simplement le module Terraform — le tout se déploie en moins de 10 minutes.

Test de bout en bout

Après terraform apply, le serveur SFTP est prêt en environ 8 minutes (l'essentiel du temps est consacré à la mise à disposition des mount targets S3 Files). Voici un test rapide :

# Upload d'un fichier
echo "Hello from S3 Files SFTP!" > test.txt
sshpass -p demo sftp -o StrictHostKeyChecking=no -P 22 demo@<sftp_endpoint> <<EOF
cd upload
put test.txt
bye
EOF

# Vérifier qu'il est arrivé dans S3 (attendre ~30-60s pour la synchro)
aws s3 cp s3://<sftp_bucket_name>/demo/upload/test.txt -
# Output: Hello from S3 Files SFTP!

Nous avons également vérifié que les clés SSH persistent entre les redémarrages de tâches — l'empreinte du serveur reste identique après un redéploiement forcé, grâce au volume EFS monté sur /etc/ssh/.

Conclusion

S3 Files comble le fossé entre système de fichiers et stockage objet d'une manière qui rend beaucoup de services AWS coûteux redondants. Pour le SFTP en particulier, la combinaison atmoz/sftp + S3 Files sur Fargate vous offre :

~8x moins cher que Transfer Family
Contrôle total sur le serveur SFTP
Notifications S3 natives pour le traitement événementiel
S3 comme source de vérité — règles de cycle de vie, réplication, analytics fonctionnent
Infrastructure as Code avec Terraform (même avant le support natif du provider)

L'époque où il fallait payer 216 $/mois minimum pour un endpoint SFTP managé est révolue pour la plupart des équipes. S3 Files est la pièce manquante qui rend le SFTP DIY sur AWS non seulement viable, mais ~8x moins cher.

DEV Community: Paul SANTUS

Cloud Native Buildpack for AWS Lambda PHP (Bref) - technical detail

Lambda's /var/task problem

Extension installation: three fallback strategies

How bref-extra extensions are built

Cloud Native Buildpack for Bref: build your app for Lambda in one command

The challenge

What my buildpack does

Testing it for real

What's not handled by the buildpack

Current state

Try it

Serverless Lazy Generation: generate once, cache forever with CloudFront origin groups (+ S3 and Lambda)

Architecture Overview: The CloudFront Origin Group Pattern

How It Works

First Request (Cache Miss)

Second Request (Cache Hit)

Key Components

CloudFront Origin Group

S3 as a Permanent Cache

Lambda as the Generator

Amazon Polly for TTS

Benefits

Cost Analysis

Pre-Generation Approach

Lazy Generation Approach (assuming 20% of content is ever requested)

Code Walkthrough

Lambda Handler Highlights

Terraform Highlights: Origin Group Configuration

Deployment

Testing

Extensions: Other Use Cases

Conclusion

Zipping 15Gb of S3 files in 6s. How the power of community made it possible.

What I took from Jérémie and Fitz

Step Functions: three limitations

1. Inline Map caps at ~40 concurrent iterations

2. Distributed Map: fast to dispatch, slow to collect

3. The 256KB payload limit

The final version: direct Lambda invocation

Results: 3000 × 5MB benchmark

What I learned (round 2)

Try it

What's next?

AWS Security Agent: 34 Findings in Under 10 Hours. A Real-World Test

Two scans, overnight

What impressed me

It thinks like a real Pentester

SQL injection: genuinely clever

A unexpected category.

Findings were validated through exploitation

Both approaches brought original content

A word on cost

From Findings to Fixes

A few more things

Verdict

S3 zipper challenge: a parallel zip assembly that beats the single Lambda approach

A Different Approach: Why Not Parallelize the Problem?

Architecture

Results

Tradeoffs

What I Learned

Try It

Keep the challenge going?

Hackez votre AWS CLI pour ajouter le support CloudShell et transformer votre terminal en bastion

CloudShell : une API non documentée

Apprendre un nouveau tour à l'AWS CLI

Se connecter à CloudShell depuis le terminal

Le problème des credentials

Le cas d'usage bastion

Ce qui ne marche pas (et j'ai essayé..)

Alors à quoi ça sert ?

Essayez vous-même

Générer des données structurées avec un LLM : quelques astuces pour plus de fiabilité

Défis

"Génère-moi un gros JSON" : les soucis

Pourquoi response_format et les schémas de function-calling ne suffisent pas

Un problème répandu

Mes solutions

Utiliser les outils comme des Builder méthodes

Pourquoi `response_format` et les schémas de function-calling ne suffisent pas

Why `response_format` and function-calling schemas aren't enough