Piculet

Security Groups

Manage EC2 Security Groups as code with a Ruby DSL

Manages: Amazon EC2 Security Groups
Language: Ruby
Package: piculet
CLI: piculet
Config file: Groupfile

The upstream repository was archived after its last activity in 2020; pin your gem and aws-sdk versions and test changes carefully before relying on it.

Groupfile

ec2 "vpc-XXXXXXXX" do
  security_group "default" do
    description "default VPC security group"

    ingress do
      permission :tcp, 22..22 do
        ip_ranges(
          "0.0.0.0/0"
        )
      end
    end
  end
end

In short

Piculet is a command-line tool that manages Amazon EC2 Security Groups as code. You keep your firewall rules in a Ruby file called a Groupfile, then apply it to update AWS. It exports current rules, shows a dry-run diff, and applies changes idempotently.

What is Piculet?

Piculet manages Amazon EC2 Security Groups as code. You write your firewall rules in a Ruby file called a Groupfile. The piculet command then makes AWS match the file, adding and revoking rules idempotently.

Security group sprawl is a common mess. Rules pile up over the years. Nobody remembers why port 8443 is open to some CIDR, and console edits leave no trail. Piculet turns the whole firewall into a text file you can review. Every opened port now gets a diff and a dry-run first. This is the idea behind codenization.

A Groupfile can hold:

Ingress rules by protocol, port range, and source
Egress rules for VPC security groups
Sources given as IP ranges or other groups

It suits teams that want focused, low-fuss firewall management. It often runs next to Kelbim, which manages the Classic load balancers those groups protect. Note the upstream repo is archived, so pin your versions.

Key facts

Manages EC2 Security Groups and their ingress and egress rules.
All firewall rules live in one Groupfile kept in Git.
A first export reveals forgotten rules and risky 0.0.0.0/0 access.
Dry-run shows every rule to be granted or revoked before you apply.
Re-running the dry-run works as drift detection for hand edits.
The upstream repo is archived since 2020, so pin your gem versions.

Illustration: Amazon EC2 Security Groups managed as code with Piculet

Getting started

Install and run Piculet

Install

Install the piculet gem (Ruby required).

$ gem install piculet

Export current state

Pull the live Security Groups configuration into a Groupfile.

$ piculet -e -o Groupfile

Dry-run, then apply

Preview the diff, then apply the change for real.

$ piculet -a --dry-run

Piculet follows an export, review, apply loop. Start with piculet -e to capture every security group in the region. On big accounts, --split writes one file per group so diffs stay short. Commit it to Git. That first export is often an eye-opener, surfacing forgotten rules and wide-open 0.0.0.0/0 access.

To change a rule, edit the Groupfile in a branch and open a pull request. Run piculet -a --dry-run to preview which permissions would be granted or revoked. Paste that output into the review. Then run piculet -a to apply. A second apply is a no-op, since Piculet is idempotent. Re-running the dry-run later catches console edits made outside the file.

Pro tip

Your very first export is a free security audit. Grep the Groupfile for 0.0.0.0/0 to spot ports open to the whole internet, then close them as a reviewed diff.

Capabilities

What Piculet can do

Export current rules

piculet -e writes your existing groups to a Groupfile. Use --split or --split-more for one file per VPC or per group, which keeps code review clean.

Dry-run before apply

piculet -a --dry-run shows which permissions would be granted or revoked, without touching AWS. Risky firewall changes are visible before they happen.

VPC and EC2-Classic support

The DSL models VPC security groups, including egress rules, and legacy EC2-Classic groups. Each is scoped per VPC with the ec2 block.

Templates for shared rules

Define a common block once, such as standard SSH or monitoring ingress. Then include it across many groups with context variables.

Targeted operations

Filter what Piculet manages with -n for named groups, -x to exclude, and --exclude-tags to skip by tag. This helps in shared accounts.

Ruby DSL or JSON format

The --format option exports and applies config as JSON instead of Ruby. That helps when other systems generate your rules.

Scoping which groups Piculet touches

Handy flags for working one group or VPC at a time in a shared account.

Option	Effect
`-n`	Limit work to named groups only
`-x`	Exclude specific groups
`--exclude-tags`	Skip groups by tag
`--ec2s`	Restrict to certain VPCs
`--split`	Write one file per group for clean diffs

In practice

When teams reach for Piculet

Firewall changes through pull requests

Opening a port becomes a one-line diff, not an unlogged console edit. Reviewers see the exact CIDR and port range in the pull request, next to the dry-run of what will be granted.

Auditing security group sprawl

One export gives a greppable list of every rule in the account. Teams hunt for 0.0.0.0/0 ingress, duplicate groups, and rules pointing at deleted resources, then remove them as a reviewed diff.

Keeping environments consistent

With templates and context variables, staging and production can share one rule set with different CIDRs. That stops environments from silently drifting apart.

FAQ

Piculet questions, answered

How do I adopt Piculet on an existing AWS account?

Run piculet -e -o Groupfile to export all current groups into the DSL, and commit the file. Nothing changes during export. After that, edit the Groupfile and apply. Piculet reconciles AWS to match.

Will Piculet revoke rules that are not in my Groupfile?

Yes. The Groupfile is declarative, so rules in AWS but missing from the file are revoked on apply. That is what makes cleanup easy. Always review the dry-run first, and use -n, -x, or --exclude-tags to scope out groups you do not own.

Does Piculet handle both ingress and egress rules?

Yes. For VPC groups the DSL models ingress and egress blocks. Each permission is set by protocol and port range against IP ranges or other groups. Legacy EC2-Classic groups are supported too.

Is Piculet still maintained?

No. The codenize-tools repository was archived, with its last activity in 2020. It still works against the aws-sdk versions it was built for, but pin your gem versions and test carefully. For an actively developed option, Terraform's aws_security_group covers the same ground. See our codenize-tools vs Terraform guide.

Can I manage only some security groups with Piculet?

Yes. Use -n for named groups, -x to exclude, --exclude-tags to skip tagged groups, and --ec2s to limit to certain VPCs. That lets you codenize one VPC at a time in a shared account.