Simon Mayes — Type II Fun

Software Quality Is Not Cyber Security

Mon, 27 Jul 2026 00:00:00 GMT

TL;DR: AI is great at writing functional code. Thoughtful prompting pushes it further — reliability, maintainability, security. But even nailing all nine ISO 25010 quality characteristics addresses only 30% of security controls. The other 70% aren’t in the codebase at all.

Building a Functional App

More people than ever are creating software. If you know your product domain, you can team up with GenAI and start writing code. Whether you’re vibe-coding all the way and never read a line, or whether you meticulously review every change and understand it all — chances are that you’ll create a highly functional app That Works on My Your Machine™️.

Next you want to share or monetise the app. You might consider — is my app of sufficient quality to put on the public internet?

Software Quality

If you’ve read my blog before you’ll know I care about software quality. You might think the next step is to take ISO 25010:2023 as a prompt and get GenAI to fix all of your issues. Give it a go — ask it to interview you and help discover all your Non-Functional Requirements and come up with a plan for addressing them.

Infrastructure

As you go through the NFRs you realise they feel out of your control. You’ve written the application code but some of the software quality characteristics are not application code — particularly reliability and security.

Who monitors the app 24/7, runs the database, ensures the servers are healthy and can handle the scale? Who secures the firewall, patches the software and manages access control?

The Realisation

You start to realise that writing application code is actually a relatively small part of operating high-quality software, that infrastructure is equally important and that security is a broad subject.

If you look into Cyber (or Information) Security you will see that there are many competing frameworks/standards: Cyber Essentials, ISO 27001, SOC 2, etc. and that they appear to explode in scope to include Physical Environment, People and Organisational Controls.

You will realise that most of these controls aren’t about code at all. They are about firewalls, policies, training, supplier contracts. Things that you cannot fix with a better prompt.

I did some analysis of the standards. I mapped 77 canonical security controls across eight industry frameworks — Cyber Essentials, ISO 27001, NIST CSF, NIST SSDF, CIS Controls, SOC 2, NCSC CAF and ISO 42001. Then I classified each control by where it lives: application, infrastructure or organisational.

The results may surprise you!

30%

pie title 77 Security Controls by Layer
    "Application: 23 (30%)" : 23
    "Infrastructure: 19 (25%)" : 19
    "Organisational: 35 (45%)" : 35

An AI-assisted, quality-focused codebase covers less than a third of the security picture. The three layers:

Application: your code, your dependencies, your tests — secure coding, input validation, code review, dependency management, threat modelling
Infrastructure: platform, network, configuration, endpoints — firewalls, patching, antimalware, encryption, backups
Organisational: people, governance, legal, operations — policies, training, incident response, supplier management, background checks

What’s NOT in the Prompt

This is the part that stopped me cold. No prompt fixes these. No code covers them:

What’s missing	Why it matters
Security awareness training	Human factor
Incident response plans	When things go wrong
Supplier due diligence	Third-party risk
Background checks	Insider threat
Physical security	Device theft
Business continuity planning	Keeping the lights on
Risk assessment	Knowing what to protect
Termination procedures	Access revocation
Privacy notice	Saying what you collect
Consent and lawful basis	Permission to process
Data subject rights	Access, correction, deletion
Breach notification	A 72-hour clock

You can tell Claude to write secure code all day long. It won’t help when someone clicks a phishing link. It won’t help when a contractor keeps access after leaving. It won’t help when the S3 bucket is public because someone misconfigured it in the console. And it won’t help when the droplet you deployed to eight months ago is three versions behind on security patches.

Even with gold-standard code, compromises come from phishing, credential theft, misconfiguration, insider threats and software you didn’t write. The application layer is necessary — but it’s not where most attacks land.

The Reality of Breaches

The most common way in is an unpatched vulnerability — and it’s almost never in code you wrote. It’s the OS packages, the container base image, the database you installed and never touched again. Spin up a droplet, ship the app, forget the box exists. Add stolen credentials, phishing and misconfiguration on top, and the shape is clear. Code can be flawless and you still get owned. (Verizon 2026 Data Breach Investigations Report)

Risk Acceptance

Unless you’re an enterprise with a GRC team, you’re not going to do all 77 controls. That’s not the point.

The point is knowing they exist — and consciously deciding which ones you’re accepting risk on. There’s a difference between “we’ve looked at background checks and accepted the risk” and “wait, background checks are a security control?”

If the app never leaves localhost:3000, there’s not much to argue about. No deployment, no infrastructure, no attack surface. Nothing at stake, nothing to protect.

The moment it’s shared, the stakes change:

Stage	What’s at stake
Personal (localhost)	Nothing
Shared (friends, colleagues)	Reputation
Public (users on the internet)	Trust, personal data, legal duties
Commercial (customer data, payments)	Money, contractual liability, career

Note where the legal duties start. UK GDPR attaches the moment you hold real people’s personal data — not the moment you start charging for it. A lawful basis for processing, a privacy notice, subject access requests, a 72-hour breach notification clock: all of that lands on the free side of the line. Privacy is the second-largest group of controls in this whole set, and not one of them is code.

Higher stakes don’t mean you need all 77 controls. They mean you need to consciously decide which risks you’re accepting — rather than accidentally skipping controls you didn’t know existed.

The jump from localhost to deployment is where the infrastructure layer kicks in. That can be manual — click-ops in a cloud console, hoping the security groups are locked down — or automated with infrastructure as code (Terraform, Helm, CI/CD). Either way, it’s a different discipline. The AI wrote the app. It didn’t write the deployment.

And even with IaC for everything, you’re now a platform engineer as well as a product developer. Different skills, different concerns, different controls.

Building secure platforms is hard and can’t be an afterthought once you’ve built your application. If you don’t have a dedicated platform team, buy rather than build — a PaaS like Vercel or Render transfers a huge chunk of your infrastructure controls to a mature, full-time provider. That’s not avoiding security; it’s transferring risk to someone better equipped to handle it.

The Framework Landscape

Maybe this is just my selection of frameworks? Maybe I picked ones that happen to be infrastructure-heavy?

So I broke it down. Different frameworks emphasise different layers — some are code-focused, some are governance-focused, some are infrastructure-focused. Here’s how each of the eight frameworks breaks down:

Framework	Controls	App	Infra	Org	Focus
NIST SSDF	16	88%	6%	6%	Secure software development
CIS Controls	36	47%	39%	14%	Technical hygiene
NCSC CAF	30	43%	33%	23%	Critical infrastructure
ISO 42001	13	38%	8%	54%	AI systems governance
ISO 27001	65	31%	29%	40%	Comprehensive ISMS
NIST CSF	41	22%	46%	32%	Risk management framework
SOC 2	50	20%	22%	58%	Trust services criteria
Cyber Essentials	12	0%	100%	0%	UK baseline certification

Percentages are rounded to the nearest whole number, so rows may not sum to exactly 100.

Look at the spread. NIST SSDF — the Secure Software Development Framework — is 88% application-focused. If I’m building software and want code-level guidance, that’s where it lives. It’s literally in the name.

But NIST SSDF is the outlier. Most frameworks aren’t about code.

Cyber Essentials is 100% infrastructure — firewalls, patching, secure configuration, endpoint protection. The UK government’s baseline certification for organisations doesn’t require writing a single line of code. You could pass Cyber Essentials with an off-the-shelf WordPress site, as long as your infrastructure is locked down.

SOC 2 is 58% organisational — policies, governance and operational controls for service providers. It cares about how you run your business, not how you write your code.

ISO 27001 — the comprehensive one, the gold standard for information security management — reaches more of these controls than any other framework here, 65 of the 77, and still puts under a third of them in the application layer.

The point isn’t that one framework is right. It’s that the broadest three here — ISO 27001, SOC 2 and NIST CSF, the ones trying to cover a whole organisation — put 31%, 20% and 22% into the application layer. The frameworks that score higher are the narrow ones: SSDF is a secure-development standard. Breadth and code-focus pull against each other.

One caveat on the maths: counting controls measures breadth, not effort or risk. “Secure coding practices” is one control. So is “background checks”. They aren’t equivalent in cost, complexity or how much they reduce your exposure. The 30% is a map of where the controls live — not a budget for where to spend your time.

One specific worth naming. Cyber Essentials’ user access control theme is counted as infrastructure rather than application, because it certifies how an organisation administers accounts rather than how developers write auth code — that single decision is what produces the 0%.

The Path Forward

flowchart TB
    app["<b>Layer 1: Application — 30%</b><br/>Secure coding · Dependency management<br/>Security testing · Code review"]
    infra["<b>Layer 2: Infrastructure — 25%</b><br/>Firewalls & network · Patch management<br/>Secure configuration · Endpoint protection"]
    org["<b>Layer 3: Organisational — 45%</b><br/>Policies & governance · People & training<br/>Supplier management · Incident response"]
    app --> infra --> org

Layer 1 — Application: Quality code is essential. This is where AI-assisted development lives. Secure coding practices, dependency management, testing, code review. Necessary — but layer one.
Layer 2 — Infrastructure: Firewalls, patching, secure configuration, antimalware. Without this, code quality is almost irrelevant.
Layer 3 — Organisational: Policies, training, incident response, supplier management, governance. The human and process layer that wraps everything else.

The Landing

AI gets you functional.

Quality-conscious prompting gets you further.

Neither gets you secure.

High-quality software is necessary. It’s not sufficient. The codebase is less than a third of the security picture — and for baseline security, it might not even be the first third to focus on.

When someone asks you to “review the code and confirm it’s secure,” the code was never the whole question.

Two interactive tools sit behind this analysis. Software Quality Meets Cyber Security maps 77 canonical controls across eight frameworks to ISO 25010 quality characteristics. Security Controls by Layer compares how each framework splits across application, infrastructure and organisational controls.

Keep the screen in your pocket

Fri, 19 Jun 2026 00:00:00 GMT

TL;DR: Don’t ditch the smartphone; reconfigure your interaction model with it. Use a constrained smartwatch (one that doesn’t pretend to be a smartphone on your wrist). Shift essential functionality to a gateway device; put the phone down and keep it out of sight.

The Thesis

A constrained smartwatch is currently the best way to rebalance your relationship with your smartphone. Intentionally use technology and keep the attention-seeking smartphone out of sight. Thoughtfully designed software can enable you to use a smartwatch as a respectful gateway device, stay appropriately connected, achieve utility and reduce reflexive smartphone usage.

Why the constrained smartwatch

Watches are the most unintrusive technology available today, originally they just passively displayed the time. Aesthetically they’re timeless, completely unremarkable and by default the screen is not in your eyeline. You have to move your wrist into an effective stress position to interact with them. They can run software, accept input (buttons, touch, mic) and return an output (screen, haptic, sound). You could create attention-seeking apps for them, but due to the limited screen, ergonomics, and physical discomfort of extended use, you’d get arm ache and no dopamine hit. The friction is a feature, not a bug.

But if the functionality is genuinely valuable — responding to an urgent message, looking at a schedule, pulling a note out of memory, asking AI a closed question — you’ll do it. Happily. Then you’ll drop your arm down and get on with your life. That is the sweet spot almost nobody is building for. Every other screen in your life is optimised to keep you on it. Infinite scroll, autoplay, pull-to-refresh, notification badges. Your watch is the opposite. It’s physically optimised to get you off it.

Why keep the smartphone

Smartphones are amazing and extremely useful, and no other devices can replace the functionality that they bestow. There are dozens of critical apps that you use weekly: messaging (WhatsApp), banking, password managers that you cannot really live without unless you seek extreme digital minimalism and discomfort. They’re excellent at letting you consume media, information, and… social media. This is the challenge: it takes discipline to separate utility and consumption, but if you have a way to keep it out of your hand, consumption can become deliberate.

I’m a software engineer. I’m not a Luddite. I like my phone — for watching videos, reading articles, browsing maps, taking photos. The phone is great at those things.

What I don’t like is reaching for it to check the weather and surfacing 40 minutes later wondering what just happened. The phone isn’t the problem. The compulsion is the problem. We use our phones reflexively — and once it’s in your hand, you’ve already lost.

How we got here

Passive feature phones and gadget era

Before the emergence of proper smartphones we had limited connectivity and loads of gadgets. I think at one point in the late 90s/early 00s my Every Day Carry (EDC) included at various times a pager, walkman (tape/CD), noname MP3 player, dictaphone, compact camera (film and then digital), calculator/torch watches etc. It started with a Nokia nk402 (5110) and I worked my way through a 3310 (which came with an amazing MP3 player btw the HDR-1), a Razr and probably a few others. WAP appeared but was barely functional and none of this technology imposed on my life. I recall long conversations with girlfriends, friends and family and the functional exchange of SMSs. (MMSs weren’t bundled in the UK and were expensive.) All these gadgets were passive and not attention seeking.

A step change came when I bought a Sony Ericsson K800i (original firmware, my favourite phone of all time). It had email, basic web, a decent camera (for the time), expandable memory (M2), tethering and music/FM radio. This changed my EDC to a phone and an A-Z pocket map (navigation apps weren’t a thing yet). Armed with a laptop (via tethering) I definitely felt more connected with more frequent email, consuming news via basic web and even have a mental image of myself on a public bus browsing the internet on my laptop (why?!). Texting had overtaken calls and conversations.

Smartphone era (no gadgets)

Then came the iPhone. The iPhone crept up on me slowly. I recall touch and non-touch smartphones of the era; they were cool and powerful but the UX sucked. Why didn’t Apple just stick a SIM card in the iPod? Well, they did, but also removed the stylus, introduced multitouch and revolutionised the UX. I let the 1st gen iPhone pass me by but bought the 2nd gen iPhone 3G. My EDC changed again… now it was just the iPhone. Smartphone apps replaced all the gadgets and life evolved to staring and stroking the slab. In the early years with basic apps and limited notifications I didn’t notice much of a change until I broke my iPhone.

Loss of control

It was only when my smartphone died that I realised how much it had crept into my life, become an extension of me and use became a reflex. This is not a unique insight but it was the first time that I paused, and considered my smartphone relationship.

Most apps are free — which means you are the product. Most apps’ incentives are to maximise use/consumption. This is so they can profile you and collect data to better target ads and “improve” their products, which is recursive. Social networks evolved into social media. Short form content became the norm, allowing companies to better A/B test and improve their algorithm. This made tech companies fabulously wealthy but has had significant negative effects on us — every pause in life was replaced with a moment of consumption. The incentives are not aligned — the smartphone was serving the app companies. Always-on communication, through the messengers (WhatsApp, Facebook messenger etc.), raised everyone’s expectation of a near-instant response, and the social pressure to engage.

Screen time became a noun. Most people know they use their smartphones too much but doomscrolling short-form content is dopamine rewarding and we unconsciously fill every gap of the day with a hit. The notification itself takes two seconds. The phone keeps you for fifteen minutes.

The Pushback

I had a decision. Replace the iPhone or adopt a dumbphone. Luckily I already had a feature phone available as I’m a climber and those early smartphones were too fragile to take up a mountain. Out came a proper dumbphone, my Nokia 105. About as simple as you can get: SMS and calls, nothing else, doesn’t even import vCard contacts, so I had to manually copy my contacts. I think I lasted 1 week. WhatsApp in my circle was a must, I used it professionally and with friends. No internet is extreme: I couldn’t even tether it to my laptop for emergency use. It may have had FM radio and basic mp3 player but I’m a Spotify guy so that was also tough. Initially I kept on picking up my phone in moments of pause but rapidly put it down when there was nothing to do, over the week this reflex faded. Adopting a dumbphone is extreme and not practical. Was there a compromise available?

I then doubled down and committed, so ironically I bought a smarter feature phone, a new Nokia 800 Tough. Surely KaiOS would save the day: it had WhatsApp (unfortunately no longer supported), tethering, email, contacts sync and an SD card slot. This time I loaded it up with some recently bought music. It worked and I tried really hard to persevere but it was buggy as hell. Email and contacts crashed daily and it was simply unworkable. It was better, and if it was workable I probably would have lasted longer but the tech wasn’t there yet. I returned it and bought an iPhone SE3.

I then looked into software app blockers and deduced that they’re either wrapping Apple’s native Content & Privacy Restrictions or a VPN loopback (I wasn’t aware of hardware app blockers like Brick or Bloom at the time). I already had a VPN and didn’t want to configure a random app to MITM all my communications, so I bypassed the wrappers and used the native platform controls. I also did the classic changes to make the phone less attractive: switch to greyscale/monochrome, reduced motion, optimised notifications, deleted apps, optimised the home screen etc. Initially this worked but over time I found the native controls too naive and coarse and found an increasing willingness to toggle them off.

Another compromise is the minimalist phone (Light Phone, Mudita Kompakt, Punkt, etc.). These are intentionally stripped-back Android phones with lo-fi screens, and some swap touch for buttons. A subset let you sideload third-party apps, with difficulty. This sounds like a great escape hatch: a lo-fi phone running your “essential” apps. But in practice it doesn’t work. They’re de-Googled, built on the Android Open Source Project (AOSP) without Google Play services, and the critical apps you need (banking, password managers) are exactly the ones whose vendors don’t support, or actively block, unsupported platforms. This was true in my case, so I haven’t explored them much further.

The most effective behaviour that worked for me was to buy a nice wireless charging dock, stick it by my front door, and not have a smartphone on my person at home. I would just suck up smartphone use when out and about. Could a behaviour or environmental change rather than willpower alone reduce phone usage?

The moment

The moment came when I upgraded my Suunto Ambit to a Garmin Fenix 5 Sapphire and carelessly left “Smart Notifications” enabled. To be clear I never wanted notifications on my wrist and didn’t even realise that this feature existed but it changed my relationship with my phone forever.

You would think that WhatsApp and other notifications on your wrist would be toxic and worse but it’s the opposite. You receive a trash notification from some WhatsApp group you love to hate — your wrist vibrates, you skim the notification (sometimes just the contact/group name), and you can immediately ignore it in less than a second without changing context. You can triage it immediately without cost. It gets noisy, so you just set Do Not Disturb (DND) on the watch for a bit. All without reaching for your phone. The alternative: your phone vibrates in your pocket. You have no idea of the source or priority, so you take it out, unlock it, and open the app. It was indeed junk, but the phone is now in your hand, so you have a quick look across WhatsApp, maybe another notification source. Slip into social media and you’ve lost. You’ve switched context, lost 20 minutes, and the personal cost is huge for zero reward.

Most notifications don’t need a reply. They need a glance and a dismiss. When your phone buzzes in your pocket, you pull it out, unlock it, read it, and now you’re holding your phone with the screen on. You’re already context-switching. With the watch, you glance for less than a second, see it’s just your mates sharing photos in a group chat, and you’re back to what you were doing. No unlock, no phone in hand, no distraction spiral. The interaction is so short it doesn’t break your focus.

Could a smartwatch be a gateway device to keep the smartphone out of my hand?

Gadgets - they’re now called wearables

I wanted to lean into the smartwatch and find the opportunity to leave my phone behind more. So I upgraded to the Garmin Fenix 7x. This gave me contactless payments (utility) and Spotify (screenless consumption). I could now regularly leave my phone behind when exercising and going out for short solo outings. It also had a torch (which is wildly useful) and the go-go gadget watch was back!

After discovering the enabler of a smartwatch I wanted to look into the vast world of gadgets and wearables and see whether, perversely, they could help me adopt digital minimalism through reduced smartphone usage. My assessment criteria were: are they remarkable, behaviourally attractive/triggering, and goal (gateway device) enabling?

Capabilities

Wearables have three types of capability: input, output and compute. Inputs: camera, microphone, buttons, biometric, location and environmental data. Outputs: display, LED indicators, haptics, headphones and speakers. Compute: cloud, on-board, or via a companion (smartphone) app — giving you rules-based deterministic or AI-based probabilistic processing. Blending these capabilities gives you either a respectful and useful device or an attention-, anxiety- and privacy-disrespecting device. Often the capabilities have a sliding scale: displays run from MIP (memory-in-pixel)/e-ink (64 colours) — unremarkable, not attention seeking — to always-on OLED, AMOLED and heads-up displays (HUD), which are attention seeking and invasive. Cameras and microphones can be selective or always-on and either invasive or privacy respecting.

Glasses

Glasses (Meta, Solos) come with various capabilities: open-ear headphones, camera, Heads Up Display (HUD), voice, and AI (normally offloaded to companion app). Can any of these help reduce smartphone usage? I believe AI and voice is a great enabler (see below) but I feel a HUD and camera would result in overstimulation and not have a positive effect. The privacy issues and hostility from others ensure that you’re always aware of them, and do not help reduce technology use. They’re remarkable and conversation inducing. AR glasses (Apple Vision, XREAL) are not considered as they’re not wearables.

Pendants and pins

Pendants and pins (Humane, Plaud) can come with: mic, camera, haptics, voice and AI. In some ways they’re very similar to glasses. They’re mainly data-collection devices and lack outputs, which greatly reduces their capability to be a gateway device.

Fitness trackers and bands

Screenless fitness bands (Whoop, Amazfit, Fitbit) are purely dedicated to biometric, location and environmental data collection and therefore do not help with the goal. They are, however, unremarkable and more discreet than the above.

Smartrings

There are two types of smart ring: biometric data-collection sources (Oura, Ultrahuman) and functional devices (NEO, CNICK, Pebble Index 01). The data-collection rings are similar to the above, but the functional ones (mic, payments, NFC) are interesting. The latter could complement a dumbphone or perform some useful action that would keep your phone out of your hand.

Smartwatches

There are two types of smartwatch: ones attempting to be a smartphone on your wrist (Apple Watch, WearOS, and arguably Pebble) and more purposeful ones with genuine smartwatch capability (Garmin). Smartwatches generally have all the capabilities apart from a camera.

A smartwatch that apes the smartphone — always-on, rich colour, feature-rich — is just a smaller attention machine on your wrist. Not what I’m after. Pebble is an interesting crossover: it’s attempting to be a smartphone on your wrist, but the e-ink display, buttons and battery physically hold it in the purposeful camp. The constraints are the feature.

I’m drawn towards low-colour, non-backlit MIP/e-ink watches from Garmin and Pebble that can be utilised in a respectful way. They’re unremarkable, discreet and can be non-attention seeking.

Headphones (AI and voice)

LLMs have opened a huge capability to talk to our devices with natural language and respond in kind. Using voice alone is hugely aligned to my goals. However it does have problems. You cannot always wear headphones, closed-ear headphones are immersive/isolating, voice input/output is non-deterministic, not always efficient and talking to yourself is remarkable. I would prefer to supplement voice with a basic display and buttons to enable rapid interaction. Visual feedback is significantly faster than voice.

An interesting aside: it appears OpenAI are working on open-ear AI headphones (see rumours on “Dime” and “Sweet Pea”). I doubt they’d be goal aligned but are one to watch (privacy/connectivity issues acknowledged).

Requirements

MUST be unremarkable, have some form of input and output and largely out of sight
SHOULD have basic display for instantaneous information consumption, buttons and haptics for discreet and silent operation
COULD have microphone for voice AI
WON’T have a rich display, camera.

There is only one wearable that fulfils these requirements.

Achieving a balance - the constrained smartwatch

It’s a balance between benefiting from modern technology and keeping your smartphone out of your hand.

The quadrant

quadrantChart
    x-axis Loses modern tech --> Keeps modern tech
    y-axis Phone stays in hand --> Phone out of hand
    quadrant-1 Modern and hands-free
    quadrant-2 Hands-free but cut off
    quadrant-3 Neither
    quadrant-4 Modern but in-hand
    Dumbphone: [0.12, 0.80]
    Feature phone: [0.30, 0.78]
    Minimalist phone: [0.42, 0.73]
    Native platform controls: [0.52, 0.22]
    Software app blockers: [0.58, 0.30]
    Hardware app blockers: [0.64, 0.38]
    Mainstream smartwatch: [0.78, 0.13]
    Phone dock by the door: [0.80, 0.55]
    Constrained smartwatch:::gateway: [0.80, 0.84]
    classDef gateway color: #b85a2a, radius: 8

App blockers demand willpower while the phone stays in your hand. Dumbphones actually work, but you lose WhatsApp, maps, banking, boarding passes — everything modern life requires. The quadrant that’s both modern and hands-free is basically empty.

I would personally recommend the Garmin Fenix 8 Solar, any older (or secondhand) Garmin MIP or a Pebble watch. A decent smartwatch (which specifically doesn’t attempt to be a smartphone on your wrist) enables you to keep your phone out of sight for the majority of the time, to be intentionally connected, and to perform quick actions, but notably keeps the phone out of your hand and significantly reduces screen time.

Garmin and Pebble are uniquely placed to enable this space. The Garmin Fenix 8 Solar is the ideal device. It has a low-colour display, an onboard mic, contactless payments and music. My current EDC is a Fenix 7x, Pixel 10 Pro, and I hope to unlock voice with a Core Devices Index 01 (smart ring with mic) when it ships. I have other AMOLED and mic Garmin watches for app development, but my technology choice is intentional and considered. I do not want a rich-colour, backlit, attention-seeking display on my wrist.

When your watch can handle messages, notes, and quick actions, reaching for your phone becomes a choice instead of a reflex. You pick it up when you want to — not because you have to. The phone goes back to being a consumption device, used deliberately for what it’s genuinely good at. Your watch handles the rest.

Disclosure: I build Untether — apps for Garmin watches so I can leave you can leave your phone out of sight.

Stop generating, start rendering: personal apps backed by your System of Record

Sun, 07 Jun 2026 00:00:00 GMT

How fighting AI content-bloat pushed me to fix my System of Record — and got me a one-shot, dependency-aware roadmap that beats GitLab’s native date-based one.

The trap

AI is amazing at rapidly generating huge volumes of content and mockups. This is a blessing and a curse which I immediately fell into. This all started with me trying to do a planning session. GitLab didn’t give me the roadmap view I wanted, so I never bothered to maintain all the epic metadata and relationships — I kept them in my head. I initially shared this extra hidden knowledge with AI and got it to cross-reference it with my KB and GitLab. It created a very pretty, accurate static HTML roadmap with the extra info included. But it hit me in the face that this data now only resides in this artefact and would immediately rot. Ideally it should live in GitLab (my SoR) or if it doesn’t fit there in my Knowledge Base.

What’s the rule? If it can fit into your System of Record and is a canonical record, maintain it there. Do not duplicate.

System of Record (SoR)

The authoritative source of truth for a given set of data — the one place that holds the canonical copy, that everything else syncs from. For work items that’s your tracker (GitLab, Jira); for code, your Git forge. It’s about authority over data, not documentation — if two systems disagree, the SoR wins.

The rot

Managing context and knowledge is hard and all AI wants to do is verbosely generate more. I’ve been managing mine in markdown and Obsidian for years — it’s not bad but it goes stale quickly, only grows, is not very well cross-referenced and frankly was a mess. I also maintained a project management system but it suffered from some of the same flaws and doesn’t quite work in the way I want it to.

PKM & KB

A Personal Knowledge Management system (PKM) is where you keep your own notes and thinking — Obsidian, a pile of markdown, your “second brain”. A Knowledge Base (KB) is the shared, team-facing version. Either way it’s human-readable knowledge — how things work, what you decided — not structured records.

AI needs high-quality context and access to your current (not stale) knowledge. AI also works best with strict spec-driven development with fixed defined scope and goals (that sounds a lot like epics and tickets…)

Both you and AI need a common System of Record. AI can hit up the APIs to fetch the work items and you can fight the UI to maintain them.

The two UXes

The human UX on most tools is generally bad; bloated, slow and too many clicks (looking at you, Jira) or too lean and minimal (GitHub). I personally favour GitLab for completeness but I struggle to view the work items at a suitable resolution (roadmaps and strategy). The robot UX is either REST or GraphQL API, and AI is expert at both. GraphQL is optimal because the AI can pick and choose the exact data it needs and minimise token burn.

The payoff

The payoff: a live roadmap better than GitLab’s own, backed entirely by canonical SoR data — and building it made me improve the records themselves.

So I vibe-coded a personal app. I knew GitLab Pages could do this quickly and securely — it has a decent API with public-client PKCE. And boom. It converted my roadmap into an app backed by canonical SoR data. Better still, building it made me improve the records: populating metadata, standardising templates, building relationships. This is something I would never have done via the GitLab UI — it’s too slow and it doesn’t always surface properly in my mental model. But shouting at Claude with Wispr Flow is one of my favourite pastimes. Collaborating with AI is much more fun than doing it yourself.

So I now had the visual aids that I needed, which were live, and AI had the rich data in the SoR. It was now less likely to rot, because the live view always reflects the SoR.

Security

Use OAuth and let your app consumers authenticate securely with their own credentials to access the app. This ensures that data stays secure and only the right people can access it. Do not save a copy of sensitive SoR data and share it outside your existing controls. Do not bake sensitive tokens or secrets into the frontend app.

And mind the token after login: PKCE protects the code exchange, not what you do with the token afterwards. Keep the access token in memory, never localStorage. Request the narrowest scope that works (read_api, only adding write where you genuinely need it — like updating a snippet). Your frontend is only as safe as your XSS and CSP posture, so treat both as existential.

What else could you build?

Decks/Presentations vibe-code a private gitlab pages site and for each slide populate the slides with Title: &epic .title, &epic .description #Summary. Or #ticket .note. Cross-link back to the canonical source so collaborators want to see the canonical source for more info.
Collaborative microsites vibe-code a private gitlab pages site where each page is a ticket #ticket .title, .description, label it as page::/the-big-idea. Encourage collaborators to comment/edit on the tickets (auto capture the history/changes) and render them inline. Enable page interaction with (GitLab) ticket emoji reactions and project stars.
Workshop collaboration space vibe-code a front-end for your project wiki (all wikis are ugly). Edit inline and push the changes back.

(&epic and #ticket are GitLab notation. .attribute #title are made-up selectors for the record details etc.)

Need printed material? Print to PDF in the browser and make extensive use of @media print CSS. Or need a different format, go bananas with URL.createObjectURL(blob) or window.showSaveFilePicker() and allow people to download dynamically generated artefacts where the canonical source is the SoR.

It doesn’t matter that these personal apps might be short-lived. Code is now cheap — which is exactly why well-structured data and knowledge in your SoR is priceless.

Takeaways

Identify your SoR (you likely already have one without fully appreciating it).
Define what lives where and try to use the fewest SoR/data repositories.
Define their boundaries, relationships and workflows. Vibe-code some apps backed by your SoR (you can hook up APIs to multiple) and ensure that data stays in one place.
Do not create more static content.
Be security conscious.
Use frontend OAuth flow so data remains gated behind your existing auth.

You, your team, and your AI will benefit.

Pixie apps

After the initial draft of this post I wrote up the pattern separately at Vibe-Coding Shareable, Infinitely Scalable Personal Apps.

The Build

Claude build me a React SPA, use the GitLab API (implementing public PKCE - no secrets) and render all my epics as cards. Display labels and appropriate metadata. Match the epic and label colours.

Wow. That was easy. Now to sort them.

Claude I can't afford GitLab Ultimate (I only have Premium), so epics don't have parents. Instead I label parent epics as X and child epics as Y and link them as related items. I want to display parent epics as swimlanes. Child epics are linked as blocked or blocking. Fetch all epics and display them top left to bottom right sequenced in blocking order.

Boom. In 30 mins I have a roadmap based on dependencies that is significantly better than GitLab’s native date-based Roadmap.

Claude when I click on a child epic card, highlight the critical path and filter out swimlanes that are irrelevant.

Now I have a clear view of my critical path and a clear visual aid of where I am at.

Claude when I click on a card, bring in a ⅓ side panel on the right that has all the epic details.

Claude find my epic templates and create a linter to highlight poorly written epics. Parse the description sections/components against the template, highlight missing items and add a warning glyph to the epic card.

Claude fetch all my labels from GitLab and interview me to understand my workflow. Update the linter to show missing or noncompliant labels.

I could go on ad nauseam. But hopefully you get the point. I now had the clearest view of my roadmap ever.

The Live View

I then went back to the static roadmap AI had built only a few hours earlier. It was already wrong — I’d added relationships and made edits since — while the live view was never out of date. Both my AI and I now work from the same current picture.

I also stress this is only a view. I am not trying to replace GitLab and build a competing UI. That is madness. I dictate with Wispr Flow to Claude for mass updates and refresh. I still use the GitLab UI for most tasks.

I cannot overstate the value of this milestone. I now have my SoR up to date. I’m now motivated and have the tools to keep it up to date — and AI will consume exactly the same information.

It’s now key to document the workflow so both you and AI are on the same page.

Claude update my user CLAUDE.md with the workflow in which I manage my System of Record (GitLab). Rehearse with me how you fetch and link work items and document API quirks.

* GitLab’s APIs are spread across REST and GraphQL, with deeply nested GraphQL structures, and it can be a challenge to fetch the right thing. Ordering work items on epics and boards takes a bit of experimentation.

Bonus: Shared State and Storage

I then continued to refine my backlog but it was difficult for my AI to understand what I was looking at and discussing.

Claude add a copy button to each work item that copies the GitLab work item reference to the clipboard.

Even this got a bit tedious after a while. So I wondered how I could give AI access to the page…

I could bastardise a work item and labels in the SoR but I figured I’d eventually need some settings and state — so a GitLab snippet (same as a GitHub gist) would be just the thing.

Claude create a private user GitLab snippet and update it whenever I click on a work item. Whenever I talk to you about a work item, query the snippet for context.

Claude was running as a limited service account, so couldn’t access my private snippet. So I had to create a private project snippet instead.

Claude add a "Share" button, which creates a private user configuration project and an empty snippet. Add an option to add a service account as a Reporter member to the configuration project. When I click on a work item, update the snippet with the current item in focus. Whenever I talk to you about a work item, query the snippet for context.

Now you can store simple state and as a bonus share it with peers that access via the API.

Hand written by me. Copy-editted by Claude. I used em-dashes before the slop, they’re my style and here to stay.

Vibe-coding shareable, infinitely scalable personal apps

Sat, 06 Jun 2026 00:00:00 GMT

PKCE for the backends and APIs you already trust: add OpenRouter to make them smart — all for free, or next to nothing.

I’ve built two personal apps with no backend at all — marshal.msyea.com (GitLab roadmaps, my way) and affinity.msyea.com (understanding my music taste with Spotify and AI). No server, no database, no running costs: each user brings their own storage and their own AI spend, so my costs never grow — however many people use them. PKCE is pronounced pixie, so that’s what I call them: Pixie apps. Here’s the pattern.

flowchart LR
    you([You])
    subgraph host["Static host: GitLab / GitHub Pages"]
        app["Pixie app (React + Vite SPA)"]
    end
    provider["Provider API + your storage"]
    ai["OpenRouter (AI models)"]
    you --> app
    app -->|OAuth 2.0 PKCE| provider
    app -->|OAuth 2.0 PKCE| ai

No server in the middle — the static page in your browser talks straight to each provider, authenticated as you.

Most apps have a missing feature or a nit that’s hugely frustrating, or there’s a workflow you can’t quite achieve with what you already use. Building personal local-first, self-hosted, or unhosted apps is a time-tested answer — and the architecture below makes it safe and quick.

Personal apps aren’t production apps

I write about software quality and take it seriously — so to be clear, this is deliberately not that. Matching your engineering rigour to the stakes is part of the discipline, and a personal app’s stakes are low: with a careful architecture you can smash these out and happily skip the production apparatus — tests, CI gates, observability, scale. The one thing you don’t get to skip is security. These apps hold live tokens and a money-spending key, so that bar stays high.

How to get the data?

Most APIs require a token. Most tokens are secrets. Managing and distributing them is difficult and requires proper infrastructure. Luckily there is another way to establish trust. Introducing the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange), as a public client. PKCE (without a secret — yes, I’m looking at you, GitHub) is the pixie dust that lets web apps fetch API tokens in the browser and hit up APIs directly. Static API tokens and other OAuth flows that require a client secret (a confidential client) are immediately dismissed. The Device Authorization Grant (device code) is considered, but the public PKCE flow is better UX (no copy/paste).

What type of app?

The public PKCE flow really points to a web app. I could consider a localhost or Electron-style app, but I want to be able to share the app easily and access it from multiple devices.

My other constraints: I want zero-maintenance, minimal security concerns, and for it to be basically free — and I also want AI. This points towards a static site hosted somewhere, and the key AI unlock — OpenRouter supports the public-client PKCE flow.

Where to host?

The obvious vibe coder’s destination of choice would be GitHub, but i) I’m a GitLab guy, and ii) GitHub does not support the public-client PKCE flow (community discussion). If you’re not intending to use GitHub as a backend (see below), GitHub Pages is still a great place to host.

How to build?

I would advocate using React+Vite because there is so much training data there and Claude (or your AI of choice) will just nail the scaffolding. If you’re an expert in another static site/frontend framework, or feeling fruity, use whatever you like.

Security

You’re holding sensitive API keys in the browser, so XSS is the risk that matters — if hostile JavaScript runs in your page, it can read anything the page can, tokens included. Be careful rendering third-party, unverified user-generated content (UGC), consider the blast radius of what you’re exposing, lock down a CSP, and escape/sanitise any HTML you consume from an API.

XSS

Cross-site scripting — an attacker getting their JavaScript to execute in your page, where it can read tokens from localStorage and call your APIs as you. It’s the main threat for a browser-only app.

CSP

Content Security Policy — a browser policy (set via a header or meta tag) that restricts what your page can load and, crucially, where it can send data. Locking connect-src to just your providers is the control that contains a leaked token.

Secrets

Use OAuth with public-client PKCE and short-lived tokens. Do not hardcode sensitive tokens or secrets into your frontend app. Consider carefully what OAuth tokens you persist to localStorage.

Access Control

Your app consumers will authenticate with their own credentials. The API will resolve access controls automatically. Use minimal scopes where possible. Consider only fetching elevated scopes just-in-time before privileged actions.

Storage

The obvious place to store data for a backendless static site is to use localStorage, but I want this app to work across devices — so I do need some form of backend. Luckily there’s a huge choice. I have another requirement — your users bring their own account and use their own storage (free or otherwise). I don’t want any running costs if my app goes viral. I have therefore discounted Firebase/Supabase.

Take Marshal, my GitLab roadmap app. Its entire data layer is: log into GitLab with PKCE, then read and write a JSON blob to a snippet through the Snippet API — that persists state across all my devices. The app itself deploys as static files to GitLab Pages. No database, no server. (For Affinity I’d extend the same idea to Google Drive.)

Here are the providers I weighed against the same checklist — how you authenticate, where your data lives, and whether it needs a BFF (see below):

Provider	AuthN	AuthZ	Client Type	BFF¹	Storage	Comments
GitLab	OIDC	OAuth 2.0 + PKCE	Public	No	Snippet or Repo File	Git Forge
Google	OIDC	OAuth 2.0 + PKCE	Public	No	App Data Folder	Google Drive · `drive.appdata`
Microsoft	OIDC	OAuth 2.0 + PKCE	Public	No	App Folder	OneDrive · `Files.ReadWrite.AppFolder`
Apple	OIDC	Apple-proprietary²	Mixed	Yes	CloudKit Private DB	Requires $99/year developer program.
GitHub	Pseudo-auth via `/user`	OAuth 2.0 + PKCE (secret required)	Confidential	Yes	Gist or Repo File	Git Forge

¹ Backend for Frontend (BFF) — you can unlock these providers with a minimal Cloudflare Worker (see below) if they’d be killer for your app.
² Apple’s various resource APIs are distinct from their “Sign in with Apple” API.

Apple (CloudKit storage)

CloudKit looks genuinely awesome — public, private, and shared databases. If I were prepared to build a BFF, weren’t a GitLab guy, and had an iPhone, I’d seriously consider it.

AI

Thank you, OpenRouter! None of the frontier model providers make it easy to use your API credits in third-party apps — but OpenRouter does. It implements a clientless (you don’t even need a client ID) PKCE flow to mint an API token. You can use any of their models through a single OpenAI-compatible API — and even implement tool use directly in the browser with a capable model.

Provider	AuthN	AuthZ	Client Type	BFF	Storage	Comments
OpenRouter	N/A	OAuth 2.0 + PKCE	Public	No	No	User pays-as-you-go per model; chat + embeddings, no persistence

A word of warning

That OpenRouter key spends real money and it lives in the browser, so treat any XSS as a financial compromise, not just a data leak. Bound the blast radius: on the consent screen set a spend cap on the key, give it a short expiry so a leaked key dies quickly, request least-privilege scopes, and prefer keeping it in memory (re-auth on reload) over persisting it to localStorage. OpenRouter sanctions this public-client flow — but you should still cap the downside.

APIs I’ve looked at

Provider	AuthN	AuthZ	Client Type	BFF	Storage	Comments
Spotify	Pseudo-auth via `/me`	OAuth 2.0 + PKCE	Public	No	No	Web Playback SDK + limited Web API³
Last.fm	Pseudo-auth via `user.getInfo`	Proprietary	Confidential	Yes	No	Rich music data⁴
SoundCloud	Pseudo-auth via `/me`	OAuth 2.1 + PKCE (secret required)	Confidential	Yes	No	Rich APIs; read/write playlists⁵

³ Spotify has two surfaces: the Web Playback SDK plays audio in the browser tab, while the Web API (data + playback control) is heavily limited since the Nov 2024 endpoint deprecations — you can fetch limited data and queue tracks. The Web API does expose ISRC (a unique cross-service recording ID) for matching tracks against other providers.
⁴ Scrobble history and tags. No ISRC — matches on name / MusicBrainz MBID.
⁵ Read/write playlists and upload audio. Partial ISRC (on uploads only).

Backend for Frontend (BFF) — the escape hatch!

Health warning

Do not do this unless you genuinely know what you’re doing. Authentication or authorisation is hard, and vibe coders may cock this up and create real security issues.

Some great APIs don’t support OAuth 2.0 + PKCE as a public client. A BFF is the escape hatch. You can cheaply build one in Cloudflare Workers; it can do the extra API authentication or bypass CORS, enabling you to consume other great APIs.

CORS

Cross-Origin Resource Sharing — a browser-enforced policy that blocks your page from calling a different origin unless that server returns Access-Control-Allow-Origin headers. A Worker runs server-side, where CORS doesn’t apply, so it can call the API and relay the response back to your page.

Confidential clients dance

Store your client ID and client secret in the Worker (as Worker secrets), handle the redirect, and either proxy API calls on behalf of the browser or — if acceptable — pass the API token down to the browser (if CORS allows).

API proxy

Some APIs have CORS restrictions and won’t work from your domain. You can proxy those calls through a Worker to get around it. Some API calls also require signing — you must not share the secret key with the browser, so do the signing in the proxy.

Apple (proprietary auth)

Apple has some amazingly useful APIs, but they use proprietary authentication mechanisms involving certificates, identifiers, and profiles — all of which must be done server-side.

Watch out: providers that gate by user count

Some API providers impose serious limitations that undercut the “costs never grow” promise — access is restricted to small test groups or individual users. I hit this with the Spotify app: since their February 2026 Development Mode changes you have to invite individual users and are limited to 5 (down from 25), with a Premium account required. If an API has this limitation, don’t hardcode a client ID — tell the user to get their own and store it in the best place you have (localStorage in the browser). Or, if it’s a secondary API call, store the client ID in your third-party storage system — the client ID isn’t a secret, so in this instance it’s acceptable.

A prompt to start from

I won’t pretend I one-shot Affinity from a single prompt — real apps take iteration. But this is the shape of spec I’d hand an agent: tight scope, and the security constraints I wouldn’t let it skip. Adapt it.

Build "Affinity", a purely client-side static web app that analyses my
Spotify taste with AI. NO backend, NO server, NO database, NO serverless
functions — everything runs in the browser and deploys as static files to
GitLab Pages. Stack: React + Vite, no router.

THREE FEATURES ONLY — do not add anything else:
1. Spotify login via the OAuth 2.0 Authorization Code flow with PKCE as a
   PUBLIC client (no client secret). I paste my Spotify Client ID on a
   login screen; persist it in localStorage, never hardcode it. Redirect
   URI = window.location.origin (no sub-path). Request the minimum scopes
   needed to read my profile and top tracks/artists.
2. Fetch my Spotify data: profile (/me) plus my top tracks and top
   artists.
3. AI analysis: connect to OpenRouter via its PKCE flow (public client,
   no secret) to mint a per-user API key, then POST my taste data to the
   OpenAI-compatible chat-completions endpoint (raw fetch, model
   google/gemini-2.5-flash) and render the written analysis.

SECURITY IS THE PRIMARY REQUIREMENT. This app holds live OAuth tokens and
a money-spending AI key in the browser. Apply ALL of the following, and
flag anything you cannot satisfy:
- No client secret anywhere, ever. Both providers use public-client PKCE
  only. If a flow appears to need a secret, STOP and tell me — never
  hardcode one.
- PKCE done correctly: a cryptographically-random code_verifier; an S256
  code_challenge; store the verifier in sessionStorage; generate and
  VALIDATE a state parameter (CSRF); exchange the authorization code
  immediately; clear the verifier after exchange.
- Inject a strict Content-Security-Policy at build time (Vite plugin).
  Lock connect-src to ONLY Spotify's and OpenRouter's API/auth hosts —
  nothing else. No unsafe-inline or unsafe-eval for scripts. Set the
  referrer policy to no-referrer.
- Keep the OpenRouter API key IN MEMORY only (never localStorage) — it
  spends real money, so a leak must die quickly. You can't set a spend
  cap or expiry through the PKCE flow, so show the user an interstitial
  telling them to set a spend cap (and short expiry) on their key on
  OpenRouter's consent screen. The Spotify token may go in localStorage.
  NEVER log a token or the key, and NEVER send either anywhere except the
  provider it belongs to. Strip the auth code and state from the URL
  after exchange; prefer re-auth over a persisted refresh token.
- No eval. No innerHTML or dangerouslySetInnerHTML with untrusted data.
  No inline event handlers. Rely on React's default escaping for any text
  rendered from a Spotify or AI response.
- Never commit secrets or personal data; the Client ID is entered at
  runtime.

Keep it minimal and readable. Show clear connect/disconnect state for
both Spotify and OpenRouter. That is the entire MVP.

That’s the whole pattern: vibe-code a static frontend personal app, wire it to the free storage you already trust with PKCE, and let OpenRouter make it smart — no server to run, no bill that grows with your users.

That’s a Pixie app: a static page, a bit of magic, and a backend that was never yours to run.

Built with this pattern

These apps are raw and not optimised for mobile — they’re personal apps, built for me, but they might be useful to you too. Grab the source below and contribute.

Project	What it is	Stack	Live	Source
Affinity	Spotify taste analysis with AI	Spotify · OpenRouter	affinity.msyea.com	msyea/affinity
Marshal	GitLab roadmaps, my way	GitLab · Snippet storage	marshal.msyea.com	msyea-sa/marshal

Hand written by me. Copy-editted by Claude. I used em-dashes before the slop, they’re my style and here to stay.

Software Quality: Adopting Common Industry Language

Thu, 14 Aug 2025 00:00:00 GMT

It’s been my observation that engineers don’t talk about Software Quality, they get stuck in word-spaghetti soup talking about the numerous types of automated tests covering various characteristics; security, availability, accessibility etc. Each set of characteristics has different stakeholders; InfoSec team, compliance team, UX team etc. and the importance of each tends to be political within the organisation. I want to focus on Software Quality in the holistic sense and suggest some clear language to describe the discipline.

The first issue is; what are we talking about? We are talking about Software Quality a simple, self titled phrase that encapsulates everything. There is no need to rebrand this term for your specific organisation.

mindmap
  root((Software Quality))
    )Engineering Excellence(
    )Service Maturity(
    )Immunisation(
    )Software Standards(
    )Engineering Playbook(
    )Compliance(
    )Checks(
    )Software Health(
    )Service Readiness(

Various organisational terms that might be synonyms for Software Quality.

All this word-spaghetti just complicates things. It then further complicated by external stakeholders. You often find that experienced engineers organically introduce tools over time but once your organisation hits a certain point you spin up InfoSec teams, Compliance teams, Risk teams, UX teams and start caring about Info and Data security, compliance, risk, performance and accessibility as separate disciplines. The list can then be endless. Those teams then speak to vendors, senior leaders and purchase tools, which may not be suitable but are subsequently mandated for use. This introduces politics and distances the concern of software quality from the engineers to the external stakeholders and sometimes results the engineers developing the behaviour of — “it’s a tick box I must fulfil before production”.

The cherry on the cake is the when people start talking about tools — which are brand names and frequently have no meaning by themselves. “Make sure your [Aqua|Wiz|Sonarqube|k6|Lighthouse] scans are passing.” All of this increases the cognitive load on engineers and is mumbo-jumbo and foreign to new engineers. How are they meant to know all the different tools you use and critically, what is the value and importance of each?

Software Quality as a term is important as it is something every engineer should care deeply about. It transcends all technologies, tools and levels of experience. All these organisational behaviours complicate things and have the effect to change engineers’ behaviours to turn software quality (not that you call it that) into a separate tick-box exercise. In some cases as engineers don’t care about some of the checks they think, “how can we bypass this” or “can we get an exception for that”.

So what is the solution? The first step is to adopt precise, universal and relatively plain language based on industry standards.

Software Quality (SQ)

“The degree to which a system or software product enables specified users to achieve specified goals with effectiveness, efficiency, satisfaction, and freedom from risk in specified contexts of use, evaluated through nine quality characteristics, including functional suitability, performance efficiency, and security.” — ISO/IEC 25010:2023 — Systems and Software Quality Requirements and Evaluation — SQuaRE

You then need to define what are these stated and implied needs? A established way to describe this is through requirements — separated out into Functional and Non-functional requirements.

Functional requirements are easy — they are typically what are defined in the user story/ticket: “An actor performs an interaction and then software then responds in a defined way.” Non-functional requirements are frequently implied and specify how the product will perform: “The response will be within 200ms”.

Functional Requirements (FRs)

“Functional requirements specify the specific functions, behaviors, or capabilities that a software system must provide to meet user or stakeholder needs, describing what the system must do in terms of inputs, outputs, and interactions under defined conditions.” — IEEE Std 830-1998

Non-functional Requirements (NFRs)

“Non-functional requirements specify the quality attributes, constraints, or performance criteria of a software system, describing how the system should perform rather than what it does, including aspects like performance, reliability, usability, security, and scalability.” — IEEE Std 830-1998

Info

ISO/IEC 25010:2023 is principally concerned about Software Quality and doesn’t explicitly define functional and non-functional requirements. I’ve pulled a definition from IEEE Std 830-1998 instead.

Now to define what software quality characteristics to talk about. I recommend that you follow ISO/IEC 25010:2023 — which specifies the following characteristics:

Functional suitability

capability of a product to provide functions that meet stated and implied needs intended users when it is used under specified conditions

Sub-characteristics: functional completeness, functional correctness, and functional appropriateness. Testing approaches: unit tests, integration tests, acceptance tests, end-to-end tests Stakeholders: End-users, product owners, engineers, UX

Performance efficiency

capability of a product to perform its functions within specified time and throughput parameters and be efficient in the use of resources under specified conditions

Sub-characteristics: time behaviour, resource utilisation, and capacity. Testing approaches: load tests, stress tests, volume tests, spike tests, resource monitoring Stakeholders: End-users, on-call engineers, DevOps

Compatibility

capability of a product to exchange information with other produces, and/or to perform its required functions while sharing the same common environment and resources

Sub-characteristics: co-existence, and interoperability. Testing approaches: API tests, contract tests, environment tests, interoperability tests Stakeholders: System integrators, engineers, DevOps

Interaction capability (aka Usability)

capability of a product to be interacted with by specified users to exchange information between a user and a system via the user interface to complete the intended task

Sub-characteristics: appropriateness recognisability, learnability, operability, user error protection, user engagement, inclusivity, user assistance, and self-descriptiveness. Testing approaches: usability tests, accessibility tests, user journey tests, A/B tests Stakeholders: End-users, UX and QA

Reliability

capability of a product to perform specified functions under specified conditions for a specified period of time without interruptions and failures

Sub-characteristics: faultlessness, availability, fault tolerance, and recoverability. Testing approaches: chaos tests, failover tests, recovery tests, availability monitoring Stakeholders: End-users, DevOps, QA

Security

capability of a product to protect information and data so that persons or other products have the degree of data access appropriate to their types and levels of authorisation, and to defend against attack patterns by malicious actors

Sub-characteristics: confidentiality, integrity, non-repudiation, accountability, authenticity, and resistance. Testing approaches: penetration tests, vulnerability scans, security audits, threat modeling Stakeholders: End-users, security, compliance, risk, engineers

Maintainability

capability of a product to be modified by the intended maintainers with effectiveness and efficiency

Sub-characteristics: modularity, reusability, analysability, modifiability, and testability. Testing approaches: static analysis, code reviews, complexity analysis, test coverage analysis Stakeholders: Engineers, DevOps

Flexibility (formerly Portability)

capability of a product to be adapted to changes in its requirements, context of use, or system environment

Sub-characteristics: adaptability, scalability, installability, and replaceability. Testing approaches: scalability tests, deployment tests, migration tests, configuration tests Stakeholders: Engineers, DevOps

Safety (new)

capability of a product under defined conditions to avoid a state in which human life, health, property or the environment is endangered

Sub-characteristics: operational constraint, risk identification, fail safe, hazard warning, and safe integration. Testing approaches: boundary tests, fault injection tests, model verification, hazard analysis Stakeholders: End-users, safety engineers, compliance, risk

The final steps are to take the characteristics and turn them into measurable Software Quality Attributes (SQAs). SQAs enable you to create a Software Quality framework (SQF) that you can practically use. Industry standards are excellent guidelines but they don’t tell you how to actually execute them. A SQF will factor in software lifecycle, environment, software criticality, etc.

Software Quality Attributes (SQAs)

Software Quality Attributes (SQAs) are measurable properties of a software system that define its quality, typically expressed as non-functional requirements specifying how the system performs, such as performance, reliability, usability, or security. These attributes are evaluated to ensure the system meets stakeholder expectations and may be automated and asserted during development (build-time) and operations (run-time).

Software Quality Framework (SQF)

A practical approach for evaluating software quality by measuring its performance across multiple quality attributes, such as functional suitability, performance efficiency, and security. It enables systematic assessment during development and operations, often through automated testing and monitoring. Defines ownership of attributes and maps quality attributes to tools.

Adopting industry standard language will bring huge benefits across the board. It will empower engineers to understand and own domain of Software Quality. These standards, though formal, provide clear, precise definitions — functional requirements, non-functional requirements and software quality attributes — will improve communication and enable engineers better scope work. They will enable engineers to use open-source resources/documentation and AI-driven tools more effectively to develop their understanding. Clarity of language will speed onboarding, aid design decisions, and reduce miscommunication. Ultimately, improved software quality will reduce incidents, enhances customer satisfaction, and improves the company bottom line.

Over the next few weeks I will continue this software quality deep dive and publish a practical Software Quality Framework using open-source tools.

Introducing the AWS GitLab Helper

Sat, 19 Oct 2024 00:00:00 GMT

What and why?

The AWS GitLab Helper (AGH) is a tool that can be implemented in GitLab Pipelines to automatically fetch temporary credentials, secrets and parameters from AWS using ABAC.

I wasn’t happy with the suggested way of authenticating with AWS. Due to limitations of AWS OIDC provider implementation, you can only assert on the ID Token’s subject claim { "sub": "project_path:my-group/my-project:ref_type:branch:ref:feature-branch-1" }, which means you’re closely coupling security and your policies to Git References (tags or branches), which in my mind seems semantically wrong. Security should be coupled with environments and GitLab has Protected Environments — so why couldn’t I use that.

Well it transpires that you can.

Say hello to AWS Cognito

AWS OIDC when used on its own can only use limited claims (see Available keys for AWS OIDC federation). After pouring over the docs I found Passing session tags using AssumeRoleWithWebIdentity, but alas it would only work if GitLab changed their ID Token to match AWS’s schema. I eventually found Using attributes for access control in the AWS Cognito Identity Pools documentation and got very excited.

Unfortunately you cannot hack with it using the aws-cli, so I had to use the SDK for JavaScript. And it was incredibly hacky and ugly code but it worked.

The magic is in Cognito mappings:

“Attributes for access control” is 50% of the magic sauce. This takes the claims from the GitLab ID Token (JWT), and maps them to the AghCognito role. However they’re a bit janky to use directly. I don’t want my AWS Resources having to have tags like NamespacePath and ProjectPath. I describe my infrastructure using Domain, System, Service and Environment tags. I thought, if I assume a 2nd role I could rename them — assuming a 2nd role opens up the environment for abuse (changing the tags to a claim you’re not entitled to). However after too much coffee and some creative thinking I worked out a safe Trust Policy that would achieve what I wanted (it also has some extra features too).

Introducing the wild Trust Policy for AghAbac — the other 50%:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<account-id>:role/agh/AghCognito"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "aws:PrincipalTag/Environment": "${aws:RequestTag/Environment}",
          "aws:PrincipalTag/ProjectPath": "${aws:PrincipalTag/NamespacePath}/${aws:RequestTag/Service}",
          "aws:PrincipalTag/UserAccessLevel": [
            "developer",
            "maintainer",
            "owner"
          ],
          "aws:PrincipalTag/EnvironmentProtected": "${aws:RequestTag/EnvironmentProtected}"
        },
        "Null": {
          "aws:TagKeys": "false"
        },
        "StringLike": {
          "aws:PrincipalTag/NamespacePath": "*/${aws:RequestTag/Domain}/${aws:RequestTag/System}"
        },
        "ForAllValues:StringEquals": {
          "aws:TagKeys": [
            "Domain",
            "System",
            "Service",
            "Environment",
            "EnvironmentProtected",
            "UserAccessLevel"
          ]
        }
      }
    }
  ]
}

Let me explain it:

Desired Tag	Assertion	Explanation
`Domain` and `System`	`"${aws:PrincipalTag/NamespacePath}" like "*/${aws:RequestTag/Domain}/${aws:RequestTag/System}"`	The `NamespacePath` contains `root-group/subgroup1/subgroup2` and my GitLab group hierarchy is `root-group/domain/system`.
`Service`	`"${aws:PrincipalTag/NamespacePath}/${aws:RequestTag/Service}" == "${aws:PrincipalTag/ProjectPath}"`	The `ProjectPath` contains `root-group/subgroup1/subgroup2/service` and my GitLab service hierarchy is `root-group/domain/system/service`.
`Environment`	`"${aws:RequestTag/Environment}" == "${aws:PrincipalTag/Environment}"`
`EnvironmentProtected`	`"${aws:RequestTag/EnvironmentProtected}" == "${aws:PrincipalTag/EnvironmentProtected}"`	I’ve added this as in my other Policies I assert that `"Environment" = "production"` also has `"EnvironmentProtected" = "true"`.
`UserAccessLevel`	`"${aws:PrincipalTag/UserAccessLevel}" in ["owner", "maintainer", "owner"]`	This gives me the option to block `developers` from ever interacting with some resources.

So now I have a well-configured ABAC role, what can I do? In my .gitlab-ci.yml file I can add the following code:

include:
  - project: msyea-sa/aws-gitlab-helper
    file: /templates/AwsGitLabHelper.gitlab-ci.yml

variables:
  AGH_CREDENTIAL_DEFAULT: "arn:aws:iam::123456789012:role/service-role/shared-system-role"
  AGH_CREDENTIAL_PROFILE1: "arn:aws:iam::123456789012:role/service-role/service-role"
  AGH_SECRET_SLACK_TOKEN: "arn:aws:secretsmanager:us-east-1:123456789012:secret:slack-token-V6d7a8"
  AGH_SECRET_TEST_DB: "arn:aws:secretsmanager:us-west-2:123456789012:secret:db-connection-string-F1r2t3"
  AGH_PARAMETER_MAX_RETRY: "arn:aws:ssm:us-west-2:123456789012:parameter/max-retry-attempts"

test:
  extends: [.aws-gitlab-helper]
  script:
    - aws --profile profile1 sts get-caller-identity
    - echo "Max retry: ${MAX_RETRY}" # do not echo secrets — they will not be masked

The template executes in the GitLab Helper Container (hook:pre_get_sources_script). This is hugely advantageous as it doesn’t interfere with job scripts (like before_script might) and ${GITLAB_ENV} plays nicely. As it’s in the GitLab Helper Container it knows curl is available and with uname -s it can download and execute the correct version from the GitLab Package Registry. The app is written in JavaScript/node and statically compiled for Linux and macOS. This makes the download quick with no dependencies.

The AWS GitLab Helper parses the environment variables prefixed with AGH_, and, when necessary, executes AssumeRole, GetSecretValue and GetParameter commands and saves the responses. To make them available to the job it does something like:

Terminal window

export AWS_SHARED_CREDENTIALS_FILE="${RUNNER_TEMP_PROJECT_DIR}/aws-credentials"
echo "credentials" >> ${AWS_SHARED_CREDENTIALS_FILE}
echo "secrets" >> ${GITLAB_ENV}

If you haven’t used ${GITLAB_ENV} before see Pass an environment variable from the script section to another section in the same job. It’s much less janky than export $(xargs < .env).

Your AWS credentials file is populated outside the ${CI_PROJECT_DIR}, so that it cannot be accidentally saved as an artifact or committed. The secrets and parameters are also made available as environment variables.

sequenceDiagram
    participant Job as GitLab Job
    box transparent GitLab Helper Container hook
        participant AGH as AWS GitLab Helper
    end
    box transparent AWS
        participant Cognito
        participant STS
        participant SM as Secrets Manager
        participant PS as Parameter Store
    end
    Job->>+AGH: Implements AGH Template
    AGH->>AGH: Configures ID Token
    AGH->>AGH: Downloads AGH Binary and executes it
    AGH->>+Cognito: Authenticates
    Cognito->>Cognito: Maps claims to Principal Tags
    Cognito->>-AGH: Returns temporary credentials (AghCognito Role)
    AGH->>+STS: Assume AghAbac Role with AGH Tags
    STS->>-AGH: Returns temporary credentials (AghAbac Role)
    loop Fetch credentials for additional roles
        AGH->>+STS: Assume other Role with AGH Tags
        STS->>-AGH: Returns temporary credentials
        AGH->>Job: Write credentials to AWS_SHARED_CREDENTIALS_FILE
    end
    loop Fetch secrets
        AGH->>+SM: GetSecret
        SM->>-AGH: Returns secret
        AGH->>Job: Writes secret to GITLAB_ENV
    end
    loop Fetch parameters
        AGH->>+PS: GetParameter
        PS->>-AGH: Returns parameter
        AGH->>Job: Write parameter to GITLAB_ENV
    end
    AGH-xJob: AGH Binary exits and Helper Container completes
    alt GitLab Build Container
        Job->>Job: Runs your Job scripts
    end

And that is it. AGH is now available for you to use. I’ve been using it in production for a few months but I will improve the documentation and automated tests before I make it Generally Available.

Note that the AWS GitLab Helper is available under BSL → MIT license. If you have 25 or fewer employees or less than £1 million in revenue you can use it in production for free. If you’re larger than that then you will need a Commercial License or wait 4 years.

Links

Component	Location
Template	https://gitlab.com/msyea-sa/aws-gitlab-helper/-/tree/main/templates
Application	https://gitlab.com/msyea-sa/aws-gitlab-helper/-/tree/main/app
Terraform Module	https://gitlab.com/msyea-sa/aws-gitlab-helper/-/tree/main/terraform