Robert Rothenberg

At the 2026 Perl Toolchain Summit Salve Nilsen and I proposed some ideas that we have been discussing on and off for the past several months for CPANSec, for a CPAN Meta v3 Specification.

Why does the specification need to be extended?

Version 2 of the CPAN Meta Spec (CPAN distributio n metadata specification) is does not allow the addition of new data, except using fields prefixed by "x_".

However, there is a need to include additional metadata about:

• external dependencies (services, libraries, files, or environment variable)
• embedded external libraries, e.g. zlib or bootstrap.
• licensing
• vulnerability reporting
• parent-child relationships (e.g. forked project)
• fixed vulnerabilities in this fork or in embedded libraries
• code and documentation generated through automation or using LLMs
• how and where to report security vulnerabilities
• project funding and sponsorship
• how the project is supported by the maintainers
• enumeration of community health documents, e.g. SECURITY.md, GOVERNANCE.md and AI_POLICY.md

This is too much information to embed in existing META.json files, and some of this metadata exists in alternative formats, for example:

• SBOM (Software Bill of Materials) files
• Attestations
• VEX files
• Common Lifecycle Enumeration (CLE)
• Project Description (DOAP) file
• OSSF Security Insights File
• REUSE

Note that most of this data is not necessary for installing CPAN modules. It exists mainly for documentation and auditing:

• generating SBOMs for an application using its dependencies
• auditing software for security vulnerabilities
• auditing software for license compliance
• displaying the external documentation for a module such as the security policy

Specification

The specification is simple:

1. All new metadata will be saved in the CPAN-META directory at the root of the distribution and software repository.

2. All files and subdirectories saved in that directory will have well-known names.

   Currently there is automation-policy.json for the AI and Automation Policy metadaya, that I have worked with Nicolas Rochelemagne. This will be discussed in a separate blog post.

3. The metadata should never be added as "x_" keys to the META.yml or META.json files.

4. This metadata may be provided as a separate file from a distribution.

The proposed specification can be found at https://github.com/CPAN-Security/cpan-metadata-v3

To suggest addition or changes, please create an issue or pull request.

Tooling

There are not yet tools for handling the METAv3 specification.

The tools will need to minimise the workload for project maintainers.

Modules should be configurable, testable and installable without any tools that support this specification. However, metadata may be useful for tools that understand them, for example, to ensure external dependencies are met.

Thanks

Thanks to the organisers of the PTS for their hard work and hospitality, and to the sponsors who are keeping the Perl ecosystem growing:

• The Perl and Raku Foundation,
• Grant Street Group,
• Geizhals Preisvergleich,
• Vienna.pm,
• SUSE,
• Trans-Formed Media LLC, - Ctrl O,
• Simplelists,
• Harald Joerg,
• Michele Beltrame (Sigmafin),
• Laurent Boivin.

I have decided to write a successor to Pod::Readme that works as a Dist::Zilla plugin that plays well with Pod::Weaver.

The idea for Pod::Readme is that a README file that is simply a version of the module documentation isn't all that useful. It often lacks important details like the prerequisites or installation instructions, and it includes a lot of unnecessary details about functions and methods.

A README file should be short and sweet: a synopsis and description, installation instructions and requirements, links to issue trackers, source repos and author/copyright info.

As I am rewriting this, I am wondering if the installation instructions are necessary now?

Many distributions have a generic INSTALL file, generally created by something like Dist::Zilla::Plugin::InstallGuide.

Before Dist::Zilla was as widely used, another option was to add installation instructions to the README file, usually with a few boilerplate along the lines of

perl Makefile.PL
make
make test
make install

or the equivalent for Module::Build.

But this seems unnecessary. Most people are not installing modules that way.

Usually they are using a tool like cpan, cpanm, cpm or even carton. And there's arely anything unusual about a module that requires specialised installation instructions.

The only use case I can think of is to document non-Perl external libraries that are required. But that can be overcome using Alien modules or adding a separate REQUIREMENTS section to the README.

I am considering removing the generic INSTALL file from modules.

I am curious as to what other people in the Perl community think about this.

Is it still worthwhile to add generic installation instructions to distributions nowadays?

I was inspired by Daniel Stenberg's recent article Detecting malicious Unicode to write Test::MixedScripts, which tests Perl source code and other text files for unexpected Unicode scripts.

Why should you care about this?

There are Unicode characters in different scripts (alphabets) that look similar and are easily confused.

A malicious person could replace a domain name or other important token with one that looks correct, for is associated with a host or other resource that they control.

Consider the two domain names, "оnе.example.com" and "one.example.com". They look indistinguishable in many fonts, but the first one has Cyrillic letters.

Confusing Unicode might be added to your codebase through a malicious patch submission or pull request. Or it could be added as text from an email or web page that you copied and pasted into your code.

The module is easy to use, and defaults to testing for Latin and Common characters:

use Test::V0;
use Test::MixedScripts v0.3.0 qw/ all_perl_files_scripts_ok /;

all_perl_files_scripts_ok();

done_testing;

If you ran this test against a file with the URLs in the above example, you would see an error such as

Unexpected Cyrillic character on line 11 character 32

If your code has Cyrillic characters then you can add line- or region-specific notations, for example

my $host = "оnе.example.com"; ## Text::MixedScripts Common,Cyrillic,Latin

or you could use this for the entire codebase

all_perl_files_scripts_ok( { scripts => [qw/ Common Cyrillic Latin /] } );

You can also test specific non-Perl files:

file_scripts_ok( "Makefile" );
file_scripts_ok( "bin/service.sh" );
file_scripts_ok( "assets/script.js" );
file_scripts_ok( "assets/style.css" );
file_scripts_ok( "templates/index.tmpl" );

There's also a Dist::Zilla::Plugin::Test::MixedScripts to generate an author test for Dist::Zilla-managed distributions.

This is a new new project, so there are likely bugs. But please give it a try, especially if you work on modules with mixed scripts in the codebase.

Adding a SECURITY or SECURITY.md file to your Perl distributions will let people know:

1. How to contact the maintainers if they find a security issue with your software
2. What software will be supported for security issues

The contact point is very important for modules that have been around for a long time and have had several authors over the years. When there is a long list of maintainers, it's not clear who to contact.

You don't want people reporting security vulnerabilities in public on the RT or GitHub issues for your project, nor do you want a post on IRC, Reddit or social media about it.

If your software is on GitHub, you can set up private vulnerability reporting. GitLab has a similar system.

Otherwise, a single email address is acceptable. An alias that forwards to all of the maintainers or at the very least, a single maintainer who has agreed to that role will work.

It's also important to realise as a maintainer that you are not on your own when you receive a vulnerability report. You are welcome and even encouraged to reach out to CPANSec for assistance triaging and fixing the issue, as well as handling notifications and reporting.

The supported software version may seem obvious, but it's important to spell out: will you be updating only the latest version? What versions of Perl will you support? If your module uses or embeds other libraries, how will they be supported?

Fortunately it is not difficult to write a security policy. The CPAN Security Group (CPANSec) has written Guidelines for Adding a Security Policy to Perl Distributions. (Note: I am one of the authors of that document.)

The guidelines include a template for a Perl distribution with a single author that you can use as a basis for your distributions. There is also Software::Security::Policy that will be integrated with build tools in the future to help generate one.

We'd like more people to use the document and provide feedback to CPANSec to improve the advice, and perhaps add alternative templates.

You don't even have to release a new version of your modules immediately. Just adding a SECURITY.md file in the root of the GitHub repo will be helpful enough.

Note: edited for typos.

Some end of year reminders for CPAN Authors:

Do all of your modules have up-to-date contact information? If not, please release new versions with an updated email address in the AUTHOR section.

(And while you're at it, why not add a security policy to your distribution, so that people know how and where to report a security issue with your module.)

If you have a cpan.org email alias, does it forward to the correct email address?

And most importantly, if you are taking time …