NodeSecure/flags: NodeSecure security flags 🚩 (configuration and documentation) · GitHub

This repository was archived by the owner on Oct 4, 2025. It is now read-only.

Name		Name	Last commit message	Last commit date
.github		.github
images		images
scripts		scripts
src		src
test		test
.all-contributorsrc		.all-contributorsrc
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
CONTRIBUTING.md		CONTRIBUTING.md
FLAGS.md		FLAGS.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
tsconfig.json		tsconfig.json

Repository files navigation

Requirements

Node.js v20 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/flags
# or
$ yarn add @nodesecure/flags

Usage example

import { getFlags, getManifest, eagerFetchFlagFile } from "@nodesecure/flags";

// Return a Set of flags title
const flags = getFlags();

// Return the manifest file
const manifest = getManifest();

const HTML = await eagerFetchFlagFile("hasBannedFile.html");

API

getFlags(): Set<Flag>

Returns a Set containing all available flag titles.

import { getFlags } from "@nodesecure/flags";

const flags = getFlags();
console.log(flags);
// Set(18) {
//   'hasExternalCapacity',
//   'hasWarnings',
//   'hasNativeCode',
//   'hasCustomResolver',
//   'hasNoLicense',
//   'hasMultipleLicenses',
//   'hasMinifiedCode',
//   'isDeprecated',
//   'hasManyPublishers',
//   'hasScript',
//   'hasIndirectDependencies',
//   'isGit',
//   'hasVulnerabilities',
//   'hasMissingOrUnusedDependency',
//   'isDead',
//   'hasBannedFile',
//   'isOutdated',
//   'hasDuplicate'
// }

getManifest(): Record<string, FlagDescriptor>

Returns the complete manifest object containing all flag descriptors.

import { getManifest } from "@nodesecure/flags";

const manifest = getManifest();
console.log(manifest.nativeCode);
// {
//   emoji: "🐲",
//   title: "hasNativeCode",
//   tooltipDescription: "The package uses and runs C++ or Rust N-API code"
// }

getEmojiFromTitle(title: Flag): string

Returns the emoji associated with a flag title. Returns "🔴" if the flag is not found.

import { getEmojiFromTitle } from "@nodesecure/flags";

console.log(getEmojiFromTitle("hasNativeCode")); // "🐲"
console.log(getEmojiFromTitle("unknownFlag")); // "🔴"

getManifestEmoji(): IterableIterator<[string, string]>

Returns an iterator of [title, emoji] pairs for all flags.

import { getManifestEmoji } from "@nodesecure/flags";

const emojiMap = Object.fromEntries(getManifestEmoji());
console.log(emojiMap);
// {
//   'hasExternalCapacity': '🌍',
//   'hasWarnings': '🚧',
//   'hasNativeCode': '🐲',
//   // ... all other flags
// }

File Operations (Node.js only)

eagerFetchFlagFile(name: string): Promise<string>

Asynchronously reads and returns the HTML content of a flag file.

import { eagerFetchFlagFile } from "@nodesecure/flags";

const htmlContent = await eagerFetchFlagFile("hasNativeCode");
console.log(htmlContent); // Returns the HTML documentation for the flag

lazyFetchFlagFile(name: string): Readable

Returns a Node.js Readable stream for a flag file, allowing for memory-efficient processing of large files.

import { lazyFetchFlagFile } from "@nodesecure/flags";

const stream = lazyFetchFlagFile("hasNativeCode");
stream.on('data', (chunk) => {
  console.log(chunk.toString());
});

Types

FlagDescriptor

interface FlagDescriptor {
  /** An emoji to visually identify the anomaly */
  emoji: string;
  /** Title (or name) of the flag */
  title: string;
  /** Short description/warning of the anomaly */
  tooltipDescription: string;
}

Flag

type Flag = keyof typeof FLAGS | (string & {});

Available Flags

Flag	Emoji	Description
hasExternalCapacity	🌍	The package uses at least one Node.js core dependency capable to establish communication outside of localhost
hasWarnings	🚧	The AST analysis has detected warnings (suspect import, unsafe regex ..)
hasNativeCode	🐲	The package uses and runs C++ or Rust N-API code
hasCustomResolver	💎	The package has dependencies who do not resolve on a registry (git, file, ssh etc..)
hasNoLicense	📜	The package does not have a license
hasMultipleLicenses	📚	The package has licenses in multiple locations (files or manifest)
hasMinifiedCode	🔬	The package has minified and/or uglified files
isDeprecated	⛔️	The package has been deprecated on NPM
hasManyPublishers	👥	The package has several publishers
hasScript	📦	The package has post and/or pre (un)install npm script
hasIndirectDependencies	🌲	The package has indirect dependencies
isGit	☁️	The package (project) is a git repository
hasVulnerabilities	🚨	The package has one or many vulnerabilities
hasMissingOrUnusedDependency	👀	A dependency is missing in package.json or a dependency is installed but never used
isDead	💀	The dependency has not received update from at least one year
hasBannedFile	⚔️	The project has at least one sensitive file
isOutdated	⌚️	The current package version is not equal to the package latest version
hasDuplicate	🎭	The package is also used somewhere else in the dependency tree but with a different version

Error Handling

lazyFetchFlagFile() and eagerFetchFlagFile() will throw a TypeError if no flag name is provided
lazyFetchFlagFile() and eagerFetchFlagFile() will throw an Error if the provided flag doesn't exist
Flag names can be provided with or without the .html extension