Pureooze - Ramblings

Memory Bank: Labels In HTML

2025-10-07T00:00:00Z

What is the right way to label something in HTML?

This came up in something I was working on recently. I always forget the best practices for labeling so I wanted to write this blog post to help me remember... and as a quick reference when I inevitably forget 😉.

Default Accessible Names #

Some elements provide a default accessible name that can be used by screen readers to provide a label for a given element. For example in a button the value between the open and close tags is the default accessible name.

<button>this is a close button</button>

Sometimes the default accessible name is inaccurate and a separate label needs to be provided to give users accurate context. In these situations labels can help.

Imagine if the <button> in the code above needed to have X as its text. This is not very informative to screen reader users and we need a better way to indicate what this button does. There are also many elements that do not have default accessible names, so we may need to provide labels for them as well.

Labeling Elements #

The title attribute contains text to provide advisory information related to its target element. This information is often presented to users through a tooltip and read by some screen readers. Note that title is a global attribute so it is available on all HTML elements.

Unfortunately because title was introduced in very early versions of HTML there are several accessibility issues with it which created the need for more modern approaches:

the <label> element
aria-labelledby
aria-label

The <label> element provides a visible caption for an element. It is often used in user interfaces like forms to provide context on a field. Label requires using the for attribute to reference another elements via their id and it only works with labelable elements.

<div class="my-ui">
  <label for="blog">I like writing</label>
  <input type="checkbox" name="blog" id="blog" />
</div>

The aria-labelledby attribute references another element on the page to provide an accessible label. Note that aria-labelledby takes priority over ALL other methods of providing accessible names.

<span id="my-label">A label</span>
<div aria-labelledby="my-label"></div>

The aria-label attribute contains text to label an element when no other label is present. Since aria-label is not visible it is often used to provide text that is only available to screen readers. Note that aria-label does not work with some elements.

<button aria-label="Close"> X </button>

So What Should You Use? #

Using title for labelling causes issues for several groups of people (via MDN):

People using touch-only devices
People navigating with keyboards
People navigating with assistive technology such as screen readers or magnifiers
People experiencing fine motor control impairment
People with cognitive concerns

"If you want to hide content from mobile and tablet users as well as assistive tech users and keyboard only users, use the title attribute."

— The Paciello Group blog

With that in mind it's safe to say that title should not be relied on for labeling elements. The best practice is to use visible labels over invisible labels like aria-label. Prefer the use of <label> or aria-labelledby because they provide visible labels. Use aria-label if these other options are not available. Remember not to use both visible and invisible labels on the same element as the aria-labelledby attribute always take precedence.

Navigating Technical Debt

2024-03-29T00:00:00Z

We don't spend enough time doing maintenance! We have too much legacy code! We only build new features and never cleanup the old things we made! We have too much technical debt! Sound familiar? If you have been involved in any meaningful software development project – especially one that is large – you will have heard complaints like this. It's a topic that many software developers (including yours truly) are passionate about.

I would be willing to bet that if you surveyed random developers at a conference, you would find that the majority of them consider technical debt to be a significant problem in their organization. I would also be willing to bet that they could not agree on what the problem is and how to address it. The issue is further complicated by the fact that many businesses seem to not care about tech debt.

In this post I want to explore the idea of technical debt. What is it? Can we measure it? What can we do about it?

What Is Technical Debt? #

The term is used to describe things from "we don't use the shiny new framework" to "this code is not written in the style I like" and even "I inherited the code from someone else". Let's start by looking at Ward Cunningham's original definition:

Shipping first-time code is like going into debt. A little debt speeds development so long as it is paid back promptly with refactoring. The danger occurs when the debt is not repaid. Every minute spent on code that is not quite right for the programming task of the moment counts as interest on that debt. Entire engineering organizations can be brought to a stand-still under the debt load of an unfactored implementation, object-oriented or otherwise.

- Ward Cunningham

This definition focuses on technical debt being a trade-off when developing new features and that it is not always bad as long as its addressed promptly. The problem though is that unlike financial debt, who is responsible for making sure an organization can handle more technical debt? Can an organization be "technical debt" bankrupt? When organizations start thinking of this in terms of "debt" they quickly realize that there don't seem to be any consequences of the debt, so they ignore it.

Steve Freeman (whose work I first encountered in the wonderful book Growing Object-Oriented Software, Guided by Tests) describes technical debt as an "Unhedged Call Option". This definition highlights the unpredictability of cost. Unlike debt – where we know what the interest rate will be – options could be infinitely more costly than doing the work in the first place. I like this definition because it brings forth this idea that the cost can become due suddenly and without warning, and we need to understand where to focus our efforts because the "debt" is a disaster waiting to happen.

Lensing To Understand Technical Debt #

The Tarantula Nebula captured from The Hubble Space Telescope. – Photo by NASA Hubble Space Telescope

Michael Feathers has a great post – Lensing to Understand – about how we change our focus to understand a system. We focus on the high level system to identify potentially interesting areas and then drill down into details to investigate them. Once we have a better understanding, we zoom back out to see how it affects the system as a whole. The idea of "lensing" is really important when it comes to understanding technical debt.

Starting with a systems view and then drilling down into the details may be a better way to understand the system. Where do people encounter the most issues? Are some parts of the system riskier than others? What parts of the system are most likely to change in the future? These are the kinds of questions we need to be asking. Too often we focus on bits of code and forget the context of the systems it's used in – which is extremely important.

So how do we identify risks in our codebase? Adam Tornhill has a great talk on "Prioritizing Technical Debt" where he talks about how we can use metrics to identify risks in our codebase. If we have a way to find out where to focus our efforts we can get a lot more value out of the work we do – allowing us to ship quicker and build high quality features. I really liked this talk and I recommend watching it.

Adam has a few metrics that he uses to identify risks:

File Hotspots: Files that are changed frequently
Method Hotspots: Methods in hotspot files that are changed frequently
Complexity: Files that are hard for humans to understand

If we find places that meet all three of these criteria we have a high risk area that we should focus on.

Hotspot Analysis #

To demonstrate application of these metrics I am going to run them on the TwitchEverywhere code – which is a C# library I wrote for a side project.

File Hotspots #

Mountains in the distance – Photo by Danny Mc

Let's start with file hotspots. I'm going to look at commits from the past year and see which files have been changed the most. Turns out there is a simple bash command that can do this:

git log --since='1 year ago' --name-only --pretty=format: | sort | uniq -c | sort -nr

Running this on the TwitchEverywhere code gives the following results:

Data results (top 20, commit count per file for past year)

Path	Count
TwitchEverywhereCLI/TwitchConnection.cs	46
TwitchEverywhere/Implementation/TwitchConnector.cs	36
TwitchEverywhere.Benchmark/MsgBenchmark.cs	20
TwitchEverywhere/Implementation/MessagePlugins/MessagePluginUtils.cs	18
TwitchEverywhere/TwitchEverywhere.cs	14
TwitchEverywhere.UnitTests/TwitchConnectorTests/NoticeTests.cs	13
TwitchEverywhere.UnitTests/TwitchConnectorTests/PrivMsgTests.cs	13
TwitchEverywhere/Implementation/MessageProcessor.cs	13
TwitchEverywhereCLI/Program.cs	12
TwitchEverywhere.Rest/Implementation/RestApiService.cs	11
TwitchEverywhere.Rest/RestClient.cs	11
TwitchEverywhere/ITwitchConnector.cs	11
TwitchEverywhere.Irc/Implementation/TwitchConnector.cs	10
TwitchEverywhere.Rest/IRestApiService.cs	10
TwitchEverywhere.UnitTests/TwitchConnectorTests/ClearChatTests.cs	10
TwitchEverywhere.Irc/Implementation/MessageProcessor.cs	9
TwitchEverywhere/Implementation/MessagePlugins/ClearChatPlugin.cs	9
TwitchEverywhere/Implementation/MessagePlugins/PrivMsgPlugin.cs	9
TwitchEverywhere/Types/PrivMsg.cs	9
TwitchEverywhere.Irc/ITwitchConnector.cs	8

Data is nice, but it's hard to get a sense of the scale we are dealing with. Let's use a small python script to create a visualization of these file commit counts sorted from highest to lowest:

Python script for plotting the csv to a horizontal bar chart

import pandas as pd
import matplotlib.pyplot as plt

# Load the CSV file
df = pd.read_csv("myFile.csv")

df_filtered = df[df['Key'].str.endswith('.cs')]
df_sorted = df_filtered.sort_values(by='Value', ascending=False)

# Plotting
plt.figure(figsize=(25,10), dpi=50)
plt.bar(df_sorted['Key'], df_sorted['Value'], color='#26196f')
plt.xlabel('File')
plt.ylabel('Number Of Commits')
plt.title('Most Modified File By Commit Count')
plt.xticks(ticks=plt.xticks()[0], labels=[''] * len(plt.xticks()[0])) # hide labels on x-axis
plt.show()

Visualized like this there is a shocking revelation: a small percentage of files are responsible for the vast majority of commits! What if I told you that the distribution of commits per file in a codebase is common across most codebases? So common that it's a pattern that is seen regardless of factors like language, age, or size. Sounds crazy right? But we can test if it is true. I ran the file hotspot analysis on the following codebases:

Results for ASP.NET Core, Roslyn, Django and Linux

If you are familiar with the Pareto Principle – these distributions certainly seems to resemble it. It seems regardless of language, author, age and purpose – the same pattern emerges. Why do you think this is the case?

People do things because they are incentivized to do them. Adding to existing places is easier because we don't have to think about context, so it's faster to do. The social system incentivizes us to do things fast, but it comes at the cost of other things. There is a constant pressure to deliver features, and so the path of least resistance is very tempting.^[1]

Method Hotspots #

Insect wings through a microscope lens – Photo by Ash Hayes

From the previous example we saw that TwitchConnection.cs was by far the most commited to file in TwitchEverywhere. We can use the following algorithm to find its hotspot methods:

Get the commits for the file in the given time range
Get the changes for the file in each commit
Compare the current commit and the next commit
Count the number of times each method was changed between commits
Sort the methods by the number of changes
Visualize the data

Finding method changes between commits (steps 3 and 4) using git is a little tricky – since it doesn't track methods. In C# we can use Roslyn to get the changes for us and I created a small .NET project called DebtCollector.NET that can be used for this. It's a simple library that uses LibGit2Sharp to extract data out of git and Roslyn to process the code.

These are the results for the TwitchConnection.cs file:

Data table for xray results

Method Name	Count
MessageCallback	25
ConnectToRestClient	11
PrivMessageCallback	7
ClearChatCallback	7
Connect	5
ConnectToIrcClient	5
NoticeMsgCallback	4
ClearMsgCallback	4
WriteToStore	3
SaveBufferToFile	3
ConnectToIrcClientRx	3
WriteMessagesToStore	2
ClearMessageCallback	2
SaveBinaryDataToFile	2

With this data its obvious I modify MessageCallback extremely often. So this could be an interesting place to focus on during a refactoring session.

Code Complexity #

Code complexity of the MessageCallback method with a score of 18 (mildly complex)

Doing a cyclomatic complexity analysis on the MessageCallback method in TwitchEverywhere gives a score of 18 (mildly complex). It's not too complex, but I know from experience that this method is modified a lot because I was lazy and didn't make separate methods for each message type. The method signature even gives a hint to this. Instead, all the logic is in one method and ends up being changed really often. So that's something I can focus on when I refactor this file.

No Silver Bullets #

There are no silver bullets in software development.

Commit hotspots could be the result of a developer who likes to make a lot of commits. Without context, it's hard to know if this is a problem in the specific situation. Technical debt is a complex problem that can be hard to define and even harder to solve. We can use metrics like hotspots to identify, investigate and communicate these risks effectively to others.

I hope this post has given you some ideas on how to navigate technical debt in your organization. If you have any questions or comments feel free to reach out to me on Mastodon or GitHub.

Additional Notes #

Notes from Michael Feathers’ Brutal Refactoring ↩︎

Integration Testing Browser Extensions with Jest

2018-08-16T00:00:00Z

Previously I wrote about how I became the maintainer of Saka, an open source browser extension that allows users to search through and load open tabs, browsing history and bookmarks. I talked about how I came up with a solution for unit testing the extension to give me confidence with code changes. I also mentioned that there were issues with integration testing that I ran into which made it difficult to test components that relied on browser APIs.

This post was originally posted on August 6th 2017. Things may have changed since then, and this post may no longer be accurate. Proceed with caution.

Today I am happy to report that I have found a way to perform integration testing on extensions and want to share it with you in this post. But before we go down that particular rabbit hole lets first discuss integration testing and why it is useful for validating software.

The Testing Trophy #

https://twitter.com/kentcdodds/status/960723172591992832

Kent C. Dodds has written about something he calls the ‘Testing Trophy’. If you have heard of the testing pyramid before this is a similar concept — it’s a visualization of how you should prioritize the different types of testing in applications. The title of Kent’s post says it all:

Write tests. Not too many. Mostly integration.

Why does he say this? Kent notes the problem with unit tests is that they only prove individual units work as expected— they do not prove that the units can work together as a whole. Integration testing on the other hand proves that all the components in our project can actually work together as expected.

The Need For Integration Testing #

Let’s leave the world of software and look at a real world example. Suppose we wanted to build a sink for a bathroom. There are 4 components to this sink: the faucet, the basin, the drainage system and the water line. Since the drain and water line come with the building we only need to worry about adding the faucet and the basin.

We go to the store and pick a faucet and basin that we like. We bring them on site and assemble each individually. We confirm that the faucet and basin each work as expected and that they have no defects. Finally we assemble the full sink — hooking up the faucet to the water line and the basin to the drainage. After all our labor we are excited to see our sink in action so we turn on the faucet and what happens? Well…

https://natooktesting.wordpress.com/2017/08/24/x-unit-tests-0-integration-tests/

Oops! While we did check to see that the faucet and basin work on their own we forgot to check if the two were actually compatible. This is why integration testing is valuable — it proves that different components, modules and libraries work together as expected.

Solution #

Since writing my last post I have managed to get Jest working with Preact, the framework used to create Saka. Jest is a modern testing framework that can run in Node or JSDOM. I will also be using the dom-testing-library to perform the rendering and assertions on my components.

Just keep in mind that while my specific solutions will be tailored for Preact, they will still work for other frameworks — especially React — with slight modifications for framework specific libraries.

There is an example Preact extension with Jest setup for reference here: https://github.com/pureooze/extension-testing-example

Installation #

You don’t need to install the preact packages if you use a different framework

First you need to install the required dependencies:

yarn add --dev babel-jest babel-plugin-transform-class-properties babel-plugin-transform-react-jsx babel-preset-env babel-preset-react jest sinon-chrome

If you are using Preact you need to also run the following:

yarn add --dev preact-compat preact-render-to-string preact-test-utils preact-testing-library

Note that just like in the previous post we will be using sinon-chrome to mock all browser APIs.

Configuration Jest (for Preact only, not required for React) #

With Jest installed you now need to create a config to tell jest how to deal with parsing Preact. If you use another framework like React you don’t need to do this. Create a jest.config.js file in the root directory of your project with the following contents:

module.exports = {
  moduleNameMapper: {
    "^react-dom/server$":
      "<rootDir>/node_modules/preact-render-to-string/dist/index.js",
    "^react-addons-test-utils$":
      "<rootDir>/node_modules/preact-test-utils/lib/index.js",
    "^react$": "<rootDir>/node_modules/preact-compat/lib/index.js",
    "^react-dom$": "<rootDir>/node_modules/preact-compat/lib/index.js"
  },
  moduleFileExtensions: ["js", "jsx"],
  transform: {
    "^.+\\.jsx?$": "<rootDir>/jest.transform.js"
  }
};

Notice the transform property is telling Jest to apply a custom transformer on all JSX files. To make it work we also need to create a jest.transform.js file:

const babelOptions = {
  presets: [["env", { targets: { node: "8" } }], "react"],
  plugins: [
    [
      "transform-react-jsx",
      {
        pragma: "h"
      }
    ]
  ]
};
module.exports = require("babel-jest").createTransformer(babelOptions);

Create The Commands #

Add the following npm scripts to your package.json so that jest can be run from the command line:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch"
  }
}

Create The First Test #

Jest is smart enough to scan your project and run any files it finds with the .test.js extension. Create a new file called Main.test.js in the tests directory of your project with the following contents where the import Main is the component you want to test:

import { h } from "preact";
import { render, cleanup } from "preact-testing-library";
import Main from "../src/example/index";
import chrome from "sinon-chrome";

window.chrome = chrome;

test("should render Main component", () => {
  const getUrl = function() {
    return chrome.runtime.getURL("popup-content.html");
  };
  chrome.runtime.getURL.returns("http://localhost:1234/index.html");
  const { container } = render(<Main getUrl={getUrl} />);
  expect(container).toMatchSnapshot();
});

Once the file is created, open a terminal in the root of your project and run the command:

yarn test:watch

You should see jest output something similar to this (assuming the test you created passed):

Congrats! Jest has successfully run and created a snapshot for the test. Jest has created a snapshots directory where all the snapshots are stored. If you open one of them you will see something like this:

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`should render Main component 1`] = `
<div>
  <div>
    <button
      id="changeColor"
    />
    <b>
      http://localhost:1234/index.html
    </b>
    ;
  </div>
</div>
`;

The next time the test runs, Jest will compare the existing snapshot to the snapshot it takes at runtime and notify you if a difference is detected.

Conclusion #

Integration testing is valuable when we want to assert the compatibility of the components we create. As Kent C. Dodds writes:

Write tests. Not too many. Mostly integration.

You can use Jest to achieve this for modern Javascript projects and browser extensions are no different. With the help of sinon-chrome you can mock out any extension APIs that are used by your components.

Unit Testing Browser Extensions

2018-05-21T00:00:00Z

In April I became the maintainer of Saka, a browser extension that allows users to search through their tabs, bookmarks and history. The original goal of Saka was to provide an elegant tab search but this soon evolved to include recently closed tabs, bookmarks and history when the original maintainer eejdoowad recognized that users search for tabs the same way they search bookmarks and history. This was an important insight and it has helped make Saka a valuable productivity tool.

When I became the maintainer I was surprised at the absence of tests in the project. There were several components with complicated logic but no tests to be found anywhere. One of the most important things I have learned as a developer is that tests are the easiest ways to write reliable, easy to refactor code. Was the old maintainer just lazy? Did he simply not care about the quality of his code? No. The opposite in fact, he cared a lot.

This post was originally posted on August 6th 2017. Things may have changed since then, and this post may no longer be accurate. Proceed with caution.

Saka, a browser extension for searching tabs, recently closed, bookmarks and history.

The issue is that the lack of documentation on the topic means that almost no one is able to test their extension. Having no confidence in my ability to make changes without breaking the code, this was a big problem. But as fate would have it after trying a dozen different approaches I ended up finding a solution.

Why We Test #

As developers we want to be sure that the code we write today is not going to become a burden to maintain later in the lifetime of the application. One way we avoid creating these burdens is by writing tests. The great thing about tests is that outside of just verifying the behavior of functions, tests allow us to provide documentation for future developers. For example by creating unit tests we declare the valid inputs and outputs for a given function. This makes it easier to refactor code because we can have confidence that our code is working correctly when all our tests pass.

The Testing Approach #

This post will focus on setting up the environment and writing some basic unit tests. I have a separate post at this link which you can use to perform integration testing.

Solution #

In my search for a solution to testing Saka, I went through several different testing libraries like Jest, Mocha and Jasmine. One of the biggest challenges for me was that Saka is written using Preact, which causes compatibility issues with other libraries. But after following several examples online, I was finally able to put together a solution using Karma and Jasmine.

Pre-requisites #

In order to use this solution, your project should use Webpack. The example uses version 4 but this may still work with older versions. While I have not tried, it should be possible to make this work with Gulp after some configuration to make sure everything is bundled properly. You can find a sample webpack config here.

Karma + Jasmine #

If you are not already familiar with it, Karma is a tool that allows executing JavaScript code in a browser for testing purposes. While it can execute code, it is not capable of testing the code and instead relies on third party libraries like Jasmine and Mocha. When developing Saka I chose Jasmine because I had previous experience using it in other projects.

The first step to getting Karma and Jasmine setup is to install them:

yarn add jasmine karma karma-chrome-launcher karma-jasmine karma-spec-reporter karma-webpack babel-loader --dev

Before Karma can start running tests it needs to know what configuration parameters to use. In order to provide these, create a karma.conf.js file in the root of the project. I have provided a sample config here. Note that Karma is capable of running Jasmine on its own, it just needs to be told to use it via the frameworks configuration property.

Chrome #

Those of you who actually read the karma config may notice that it specifies Chrome as a requirement:

browsers: ["ChromeHeadless"]

As I mentioned earlier, Karma requires an actual browser to run the JavaScript code. This line tells Karma that it should look for Chrome on the system it is running on and launch it in headless mode. The benefits of using headless mode are that you can use the system when the tests are running, instead of being interrupted every 2 seconds when a new test starts to run. Seemed like an obvious win to me.

Adding A Test #

To start adding tests, create a JavaScript module using the code in this example under the src directory of your project. As the name suggests the sum function will simply add up all values passed to it and return the sum.

Create a test directory in the root of your project — this is where all the tests will live. Take a look at the karma config file and note this line. It tells karma that to load the tests it must use the test/index.test.js file as the entry point. In the index.test.js file add the following code to import all files inside the test directory ending in .test.js.

With the config out of the way, add a new file simpleModule.test.js in the test directory with the following code. This file will house the tests for all the functions in the simpleModule.js file. The describe blocks are used to categorize the tests in the Jasmine logs so that it is easier to tell which modules have failures. Individual tests are located within the it() function which needs a description as the first argument and the test function as the second argument. To learn more about how to write tests using Jasmine you can consult the documentation.

Running Tests #

In order to run tests the karma executable can be called directly with the path to the config file passed in as an argument. While this works, a more elegant solution is to add the command to the npm scripts in the package.json file like this. You should now be able to just run yarn test and see the output from Karma like below.

Testing With WebExtension APIs #

The problem that developers run into when attempting to test extensions is having to deal with the WebExtension APIs in tests. The problem is that the environment the tests run in — that is as a webpage in chrome — does not have access to the APIs. This becomes an issue as Jasmine will throw an error because anything with browser.* will be undefined.

To overcome this issue you need to install sinon-chrome, a library which enables mocking out these APIs.

yarn add sinon-chrome --dev

Create a new module in the src directory called popup.js with the following code. Notice how the getUrl function relies on the browser.runtime.getURL API. We are going to use sinon-chrome to mock the response the browser would return.

Create a new file called popup.test.js in the test directory to store all the tests for the popup.js file you just created. Add the following code to the test file and notice how the browser API is mocked by sinon-chrome. For every test that uses the WebExtension APIs, you must specify what each API should return when the test runner (Chrome) encounters it, allowing you to bypass the issue with the APIs not being defined.

Run yarn test and you should see the following results from the tests:

And there you are, free to test your chrome extension without having to fear the extension APIs.

Future Work #

While this setup with Karma, Jasmine and Chrome works, it is not an ideal solution. There are some benefits in using Jest, a modern testing library that runs entirely in Node thus eliminating the need for a test runner and browser. Unfortunately, Jest has some compatibility issues with Preact so for the time being I have put it on the back burner. Hopefully I can find some time to migrate the tests to use Jest because I think it will make for a good blog post.

Test Driven Development In JavaFX With TestFX

2017-08-06T00:00:00Z

A dive into how to test JavaFX applications using TestFX.

If you just want to read about how to use TestFX skip to the "Setting Up Our Application" section.

This post was originally posted on August 6th 2017. Things may have changed since then, and this post may no longer be accurate. Proceed with caution.

I recently started working at a company that has a very heavy reliance on Java applications. As a primarily Python, Javascript and C++ developer, I had not used Java for a few years so given the obvious fact that I would have to get comfortable with using Java on a day to day basis, I decided to work on a small project in Java to get my feet wet.

The Application #

While thinking about possible project ideas for this Java application I browsed through my Github repos and saw an all too familiar project, a podcast feed aggregator/player that I had worked on with some friends. The application was written using Qt 5.8 and was capable of fetching RSS feeds for any audio podcast on iTunes, stream episodes and render the HTML contents associated to an individual episode. The links shown below in the right hand side widget would also open in the default system browser when clicked on by a user.

Screenshot of the original PodcastFeed application. On the left is the podcast list, the middle is the episode list (contents change based on selected podcast) and the right is the description rendering for each individual episode.

While the application looks pretty simple (and it is) the fun of developing this came from working with two friends to learn Qt while also developing the application quickly and in a small amount of time. The reason I considered rewriting this application in Java was because the code we originally wrote had several flaws (keep in mind we developed it in a very short amount of time):

We wrote zero tests for the application (Yikes!!)
Classes were an after thought, they were not part of the initial design
Due to the above the functions were very tightly coupled
Tight Coupling made it very difficult to modify core processes of the application (like XML parsing) without breaking other features

The Approach - TDD #

Given the flaws mentioned above it became clear to me that I would need to take a different approach to this new application if I wanted any hope of being able to maintain it for any reasonable amount of time. For help with how to approach this application design I turned to a book I had been reading recently: Growing Object-Oriented Software, Guided by Tests by Steve Freeman and Nat Pryce.

Tests are a core part of development, and this book is a great source of knowledge about how to create good tests.

This book is a fantastic read if you want to learn about what makes Test Driven Development a powerful tool for use in Object Oriented development. The authors provide a lot of deep insight on why tests are important, what kind of tests should be used when and how one writes expressive, easy to understand tests. I will spare the details on TDD but you can google it or read the book above to learn more about it.

The authors of the book continuously stress the importance of using End to End tests because of their ability to test the full development, integration and deployment processes in an organization. I myself do not have automated build systems such as Atlassian’s Bamboo system so my automation capabilities are limited, but I can make use of Unit tests to test individual functions and UI Tests to try and get as much End to End coverage (between the local application and the podcast data on the Internet) as possible.

Setting Up Our Application #

Getting a JavaFX project working with TestFX 4 is actually quite simple but a lot of the challenges working with TestFX actually come from the lack of documentation by the TestFX developers. TestFX 4 in particular has at the time of writing, almost no clear documentation available. Please note that for the rest of this post I will be using examples involving IntelliJ. If you use a different IDE you may have to adjust certain steps to match your environment.

To start off, lets create a JavaFX project in IntelliJ. Once the project is created, press Shift + F10 to run it to make sure it is working. If you get an error at this step you may have configured your Java/JavaFX environment incorrectly.

The Main.java file is the one that will run at the very start of execution. It will kick off the application as well as create any widgets and scenes we specify. By default it looks something like this:

package sample;

import javafx.application.Application;
import javafx.fxml.FXMLLoader;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.stage.Stage;

public class Main extends Application {

    @Override
    public void start(Stage primaryStage) throws Exception{
        Parent root = FXMLLoader.load(getClass().getResource("sample.fxml"));
        primaryStage.setTitle("Hello World");
        primaryStage.setScene(new Scene(root, 300, 275));
        primaryStage.show();
    }


    public static void main(String[] args) {
        launch(args);
    }
}

Copy the following into the sample.fxml file, this will serve as the widget layout for the application:

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.Button?>
<?import javafx.scene.control.Label?>
<?import javafx.scene.control.TextField?>
<?import javafx.scene.layout.AnchorPane?>
<?import javafx.scene.layout.ColumnConstraints?>
<?import javafx.scene.layout.GridPane?>
<?import javafx.scene.layout.RowConstraints?>


<GridPane alignment="center" hgap="10" vgap="10" xmlns:fx="http://javafx.com/fxml/1" xmlns="http://javafx.com/javafx/8.0.111" fx:controller="sample.Controller">
   <children>
            <TextField layoutX="15.0" layoutY="25.0" fx:id="inputField" />
            <Label layoutX="15.0" layoutY="84.0" text="TEXT GOES HERE" fx:id="label" />
            <Button layoutX="124.0" layoutY="160.0" mnemonicParsing="false" text="Apply" onAction="#applyButtonClicked" fx:id="applyButton" />
   </children>
</GridPane>

Now copy the following into the Controller.java file. By binding the FXML file to the Controller with the use of the fx:controller tag, we can dictate behavior for our application using Java code.

package sample;

import javafx.event.ActionEvent;
import javafx.fxml.FXML;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.control.TextField;

public class Controller {

  @FXML
  TextField inputField;

  @FXML
  Label label;

  @FXML
  Button applyButton;

  public void applyButtonClicked () {
    label.setText(inputField.getText());
  }
}

Run the application again (press Shift + F10) and verify that entering text into the input field and then clicking the apply button causes it to be copied into the label like so:

It is clear the application runs in a very basic use case so TestFX can now be used to create UI tests to validate this belief.

Setting Up TestFX #

To start using TestFX the first step is to import the library into a project. IntelliJ makes this pretty easy, just click File > Project Structure. In the window that pops up, click Libraries > the green plus sign > From Maven. In the popup window search for testfx and select testfx-junit:4.0.6 like below and click OK:

Repeat the steps above and add testfx-core:4.0.6, hamcrest-junit:2.0.0.0, junit:4.12, loadui:testFx:3.1.2 and guava:14.0.1 to the project. You should have the following in the libraries pane now:

Now we need to create a directory to place our tests in. IntelliJ provides a really easy way to do this. Right click the project name in the Project Pane > New > Directory and name this new directory tests. Now right click this newly created directory and Mark Directory As > Tests Sources Root. Once that is done, open up Main.java and click on the class name:

Press ALT + Enter > Create Test. Now you can configure what you want to use to run these tests but for now the default will suffice. Click OK.

There should now be a new file called MainTest.java in the tests directory. This file will should house all the tests related to the Main.java file (ie. the full UI application). To begin using TestFX we need to first make some changes to our test file. Recall that in Main.java, the Main class extends the Application class. Likewise when we want to use TestFX to perform testing of our Main class, we must extend the ApplicationTest class from the org.testfx.framework package.

IntelliJ now warns us that the ApplicationTest class requires that we implement a start(Stage) method, so lets do that:

@Override
public void start (Stage stage) throws Exception {
  Parent mainNode = FXMLLoader.load(Main.class.getResource("sample.fxml"));
  stage.setScene(new Scene(mainNode));
  stage.show();
  stage.toFront();
}

We have to create mainNode in order to allow us to refresh the application after each test has run, this will ensure that we never have stale data from a previous test causing unexpected errors in our tests. Now we should implement our setUp and tearDown methods, to tell TestFX what it should do before and after it has run a test. Its important to do this because you want to ensure that your test environment is consistent with what you expect it to be “in the real world”. In our case the setUp method is empty as we don’t need to prep anything before we run a test, but as applications get more complex it becomes vital to make use of this method.

@Before
public void setUp () throws Exception {
}

@After
public void tearDown () throws Exception {
  FxToolkit.hideStage();
  release(new KeyCode[]{});
  release(new MouseButton[]{});
}

Writing Our First Test #

At long last we can start writing a test! Lets begin with a simple one that just enters text into our inputField.

Click to see the code

package sample;

import javafx.fxml.FXMLLoader;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.scene.input.KeyCode;
import javafx.scene.input.MouseButton;
import javafx.stage.Stage;
import org.junit.After;
import org.junit.Before;
import org.junit.Test;
import org.testfx.api.FxToolkit;
import org.testfx.framework.junit.ApplicationTest;

import static org.junit.Assert.*;

public class MainTest extends ApplicationTest {

  @Override
  public void start (Stage stage) throws Exception {
    Parent mainNode = FXMLLoader.load(Main.class.getResource("sample.fxml"));
    stage.setScene(new Scene(mainNode));
    stage.show();
    stage.toFront();
  }

  @Before
  public void setUp () throws Exception {
  }

  @After
  public void tearDown () throws Exception {
    FxToolkit.hideStage();
    release(new KeyCode[]{});
    release(new MouseButton[]{});
  }

  @Test
  public void testEnglishInput () {
    clickOn("#inputField");
    write("This is a test!");
  }

}

Now we can try running this test by right clicking the tests directory and clicking Run ‘All Tests’ and you should see something like this:

Great! We just got our first UI test to work. Now lets actually make it test our applications functionality:

@Test
public void testEnglishInput () {
  Label label = (Label) GuiTest.find("#label");

  clickOn("#inputField");
  write("This is a test!");
  clickOn("#applyButton");
  assertThat(label.getText(), is("This is a test!"));
}

This new version of the test will now click the Apply button after entering the text into our inputField and then attempt to assert that the label is actually set to the desired message (what we input) and not something else. Running this test now confirms our belief that our application functions as expected, thus ensuring that if we were to update our code the test would help us validate the functionality.

On a side note, notice that the assert statement is written in a format that reads very naturally in English. If we read it out we get something like "Assert that label.getText is MESSAGE". In the Growing Object Oriented book by Freeman and Pryce they discuss the importance of writing tests in this format to make them easy to read.

To finish off lets write some more tests for two additional cases. We will test French and numerical inputs.

@Test
public void testFrenchInput () {
  Label label = (Label) GuiTest.find("#label");

  clickOn("#inputField");
  write("C'est un test!");
  clickOn("#applyButton");
  assertThat(label.getText(), is("C'est un test!"));
}

@Test
public void testNumericalInput () {
  Label label = (Label) GuiTest.find("#label");

  clickOn("#inputField");
  write("123456789");
  clickOn("#applyButton");
  assertThat(label.getText(), is("123456789"));
}

Now when we run all our tests TestFX will automatically reset our application state so that our changes from the previous test do not cause errors when then next test begins.

As we can see TestFX is a very powerful framework for testing JavaFX applications. While it does lack documentation, TestFX has in my own experience provided a lot of value when I am trying to ensure that the feature of my application are working as intended. Compared to my experiences in developing a UI with Qt and no UI Testing, this project with JavaFX and TestFX has been a far more enjoyable one.

What Is PAM?

2016-08-07T00:00:00Z

The last post I did was the start of the Comprehensive Guide To AppArmor which took a look at the basics an administrator or developer needs to know to start creating and deploying AppArmor profiles for a program. In the post I also left a question for the reader regarding AppArmor being used to replace the traditional DAC permissions (but never should!) and how you could use it to remove access to a file from a specific user (rather than a program). However, this requires usage of the pam_apparmor module for PAM and due to this, before going into depth with using pam_apparmor, you should make sure you have a grasp of the basics of PAM and its configuration files.

This post was originally posted on August 7th 2016. Things may have changed since then, and this post may no longer be accurate. Proceed with caution.

Seriously What Is PAM? #

PAM stands for Pluggable Authentication Modules and is used to perform various types of tasks involving authentication, authorization and some modification (for example password change). It allows the system administrator to separate the details of authentication tasks from the applications themselves. This allows the policy to not only be generic, it means that the programs do not need to be modified in order to update the policy! An example of PAM usage is controlling login attempts to a shell/GUI interface so that only successful authentication and authorized events are allowed. You could also use PAM to control who can use the su binary to switch identities or control who can use the passwd utility to change passwords.

Overview #

When a developer wishes to interact with PAM to let it handle events, they must include libpam which allows communication via the API provided by the library. When PAM sees a new event that it must process, it will look at the relevant configuration files found in /etc/pam.d and determine which modules must be used at certain stages.

Source: http://www.tuxradar.com/content/how-pam-works

PAM is capable of using context to determine what it needs to do, for example the pam_unix.so module has capabilities for the auth and account stack. In the auth stack it checks a username and password combo while in the account stack it will check a users aging and expiration info. This versatility is one of the reasons PAM has been so popular in the UNIX world, it allows for solutions that can be combined to create a generic library to deal with certain type of request.

How Do I Tell A Program Supports PAM? #

This is usually pretty easy, you can use ldd to check if libpam is in use:

comp:/home # ldd /usr/sbin/sshd | grep pam
   libpam.so.0 => /lib64/libpam.so.0 (0x02209ddace0105400)
   
comp:/home # ldd /bin/su | grep pam
   libpam.so.0 => /lib64/libpam.so.0 (0x02999ddace0105400)
   libpam_misc.so.0 => /lib64/libpam_misc.so.0 (0x12211ddace1105400)

Configuration #

As I already mentioned, PAM configuration files are stored in /etc/pam.d for all valid programs. A line in a configuration file will look something like this:

auth sufficient pam_rootok.so

There are three parts to this line, the first is called the function type which is the PAM function (stack) that an application asks PAM to perform. The second is a control argument which is used to determine how PAM responds to a success or fail when performing the action. The final part is the module which PAM calls when it reaches this line, it will determine what PAM specifically does to validate the auth attempt.

Function Types #

There are four possible functions that can be called inside a configuration file. Each of these provides a unique context that can be used within the module.

Function Type	Description
auth	Authenticate a user, make sure they are who they say they are
account	Check user account status, ensure they are authorized to do action
session	Perform something for the users session like allocate resources they might need, for example mounting their home directory or setting usage limits
password	Change a users password or other creds

Control Arguments #

Understanding control arguments is a critical part of creating a secure PAM policy, if you mess up the order you pay the price! There are five types of simple control arguments:

Argument	Description
sufficient	if it succeeds then auth is successful and PAM does not need to look at more rules (assuming no required module failed), if it fails then keep going
requisite	if it succeeds PAM proceeds to additional rules, if it fails then PAM stops and sends a failure message
required	if it succeeds then proceed to next line, if it fails then proceeds to additional rules but will always return an unsuccessful auth regardless of end result. Useful because it will not say what caused the failure, thus an attacker will not be able to know if they got some part of the auth right
optional	the result is ignored, only becomes necessary for successful auth when no other modules reference the function
include	pulls in all lines in the config file which match the given param and appends them as arguments to the module

Module Arguments #

PAM is also capable of taking arguments and passing them to the target module. This allows an administrator to specify constraints like min/max length for passwords or if a module should run in debug mode. The following is an example of how you can pass arguments to a module:

auth sufficient pam_unix.so nullok

As you can see all you need to do is append the line with the values you wish to pass to the module. In this case the value nullok tells pam_unix that it is okay to be supplied no password at all by the user. In the case you wish to pass more than one argument to the module you can simply separate them using spaces like so:

session optional pam_apparmor.so order=user,group,default debug

Simple Example #

Now that you know what the contents of a PAM file mean, lets look at a simple example from the book How Linux Works (2nd Edition) by Brian Ward. The following is a PAM config (albiet old) for the chsh utility:

auth sufficient pam_rootok.so
auth requisite pam_shells.so
auth sufficient pam_unix.so
auth required pam_deny.so

The first line says that if the user attempting the action is root then that is enough authority for PAM, and it will consider the authentication successful and end. If the user is not root then PAM will continue to the next line.

The second line checks to see if the shell the user is attempting to switch to is listed in /etc/shells. If it is not listed there then PAM considers this an authentication failure and immediately quits. It will also output an error message stating why the failure occured. If the shell is listed in /etc/shells then PAM continues to the next line.

The third line attempts to authenticate a user via their password. If the user provides the correct password then PAM will consider the authentication successful and end. If however the password is wrong, then PAM will continue to the fourth and final line.

The fourth line in this sample file may look the same as all the rest, but it is actually special. The pam_deny module is what can be called a default deny module, it will always return an authentication failure no matter what function or control arguments call it. This is similar to the idea of how firewalls are configured with a default deny rule at the very end of the chain so that any packet which does not match a previous rule is dropped. In this case PAM will have an authentication failure and will not explain why it failed. This is a very important part of making PAM configs, make sure you have the default deny policy at the end and use the required control argument so that an adversary cannot tell what caused the failure.

In case it helps, the author was kind enough to provide a flow chart to illustrate how PAM will deal with this module:

Source: How Linux Works (2nd Edition) by Brian Ward

Practice #

Here is another example of a PAM config file:

auth required pam_securetty.so
auth required pam_unix.so nullok
auth required pam_nologin.so
account required pam_unix.so
password required pam_cracklib.so retry=3
password required pam_unix.so shadow nullok use_authtok
session required pam_unix.so

Try and write out/draw what PAM will do for this file, don’t worry too much about what the modules that are called do but focus on what each function and control argument try to do. Once you think you have it done, continue reading.

So I hope you saw that since the config file above contains only the required control argument, if there is ever a failure with one of the modules the user will not know which specific step caused the failure. This can be useful is cases when we do not want the adversary to be able to tell which of their actions caused the failure, making it harder for them to tell what they did right and what they did wrong (for example if they guessed a password, path or ID correctly).

The Big Kahuna #

Let's look at a modern chsh config for PAM:

#%PAM-1.0
auth sufficient pam_rootok.so
auth include common-auth
account include common-account
password include common-password
session include common-session

Recall the function of the include control argument:

include — pulls in all lines in the config file which match the given param and appends them as arguments to the module

This means that once PAM has finished processing the include lines, the file ends up looking like this (only in memory, file on disk is not written to):

#%PAM-1.0
auth sufficient pam_rootok.so
# common-auth
auth required pam_env.so
auth optional pam_gnome_keyring.so
auth required pam_unix.so     try_first_pass
# common-account
account required pam_unix.so try_first_pass
# common-password
password requisite pam_cracklib.so
password optional pam_gnome_keyring.so use_authtok
password required pam_unix.so use_authtok nullok shadow try_first_pass
# common-session
session required pam_limits.so
session required pam_unix.so try_first_pass
session optional pam_umask.so
session optional pam_systemd.so
session optional pam_gnome_keyring.so auto_start only_if=gdm,gdm-password,lxdm,lightdm
session optional pam_env.so

Just like the previous exercise, try and write out/draw what the flow of the PAM module will be given these modules. Remember that the required control argument only outputs a failure at the end of the run. This prevents the adversary from being able to know what step failed (no error message) and it prevents them from being able to perform a timing attack to attempt a guess at the failed step. If you are able to map out the flow of this module then you have a good grasp of PAM and should feel confident approaching any other modules on a modern Linux system!

The Comprehensive Guide To AppArmor: Part 1

2016-07-28T00:00:00Z

I wanted to do this post on the basics of AppArmor and how to get started with using it on your system. This post started as a very small guide on AppArmor but as I wrote it I felt more and more convinced it needed details to explain various features and issues. As such it has now ended up as a comprehensive guide on how to start using and understanding the AppArmor tools.

This post was originally posted on July 28th 2016. Things may have changed since then, and this post may no longer be accurate. Proceed with caution.

In case you don't know what AppArmor is, the official wiki provides a decent explanation:

AppArmor is an mandatory access control (MAC) like security system for Linux. It is designed to work with standard Unix discretionary access control (DAC) permissions while being easy to use and deploy, by allowing an admin to confine only specific applications.

Essentially AppArmor provides MAC functionality to Linux and is used to supplement the traditional DAC (file permissions) functionality that the OS provides. Using the most basic AppArmor tools an administrator can create and deploy AppArmor profiles to restrict access for specific processes. For example one could restrict the web browser to only let users access files in their home directories. This would prevent a scenario where Alice would try to upload or share files owned by Bob without his knowledge.

Getting Started #

To run AppArmor the first step is the same as all other software, make sure that it is installed. OpenSUSE and Ubuntu have it installed and enabled by default but other distros may vary. Installing AppArmor is usually as simple as checking if a distro has a package for it, then downloading and installing the package. Note that the kernel must be compiled with support for AppArmor. Once AppArmor is running you can make sure the service is running using:

systemctl status apparmor  # Checks status of the AppArmor service and tells you if it is enabled on boot
systemctl start apparmor  # Starts the service
systemctl enable apparmor  # Makes apparmor start on boot

This will ensure that the system is always up and running with AppArmor ready to enforce profiles.

Using aa-status #

Now that the service is running let's start using the AppArmor tools (aa-tools) to monitor and manage the system. To start we can use the aa-status tool to check what profiles are loaded and what status they currently have. On a fresh Ubuntu system I had something like this:

user@ae:~$ sudo aa-status  
[sudo] password for user:  
apparmor module is loaded. 
12 profiles are loaded. 
12 profiles are in enforce mode. 
   /sbin/dhclient 
   /usr/bin/lxc-start 
   /usr/bin/ubuntu-core-launcher 
   /usr/lib/NetworkManager/nm-dhcp-client.action 
   /usr/lib/NetworkManager/nm-dhcp-helper 
   /usr/lib/connman/scripts/dhclient-script 
   /usr/lib/lxd/lxd-bridge-proxy 
   /usr/sbin/tcpdump 
   lxc-container-default 
   lxc-container-default-cgns 
   lxc-container-default-with-mounting 
   lxc-container-default-with-nesting 
0 profiles are in complain mode. 
1 processes have profiles defined. 
1 processes are in enforce mode. 
   /sbin/dhclient (2092)  
0 processes are in complain mode. 
0 processes are unconfined but have a profile defined.

So right away we can see that 12 profiles have been loaded by the system and are in an enforce status. What this means is that AppArmor will monitor the processes that match these profiles and decide if a specific action is permitted or denied by the policy. If this seems confusing so far, don't give up yet, once I show some examples on what profiles look like I think this will make more sense.

One other thing I wanted to point out about this output was the complain and unconfined status. When a profile is in complain mode AppArmor will allow it to perform (almost)^[1] all tasks without restriction, but it will log them in the audit log as events. This is useful when you are attempting to create a profile for an application but are not sure what things it needs access to. The unconfined status on the other hand will allow the program to perform any task and will not log it. This usually occurs if a profile was loaded after an application is started, meaning it runs without restrictions from AppArmor. It's also important to note that only processes that have profiles are listed under this unconfined status, any other processes that run on your computer but do not have a profile created for them will not be listed under aa-status.

Using aa-genprof #

Now that we covered what different states an AppArmor profile can be in we can move on to learning how to build these profiles for a specific program. For this demo we are going to create a simple script that we will then enforce with AppArmor. You will also need to create a directory called "data" in the same directory as the script before running it for this example to work. The goal is to demonstrate that we can use AppArmor to prevent the script from accessing any other paths.

So, create the directory "data" and then create a script called example.sh:

#!/bin/bash 
 
echo "This is an apparmor example." 
 
touch data/sample.txt 
echo "File created" 
 
rm data/sample.txt 
echo "File deleted"

Make sure to give it the execute permission and then run it:

user@ae:~$ ./example.sh  
This is an apparmor example. 
File created 
File deleted

Great our script worked! Now lets start enforcing it with AppArmor. There are two main tools we use to generate and add on to profiles, aa-genprof and aa-logprof. The first is used to monitor and create a profile for an application the first time it is run (i.e. when you are first creating the profile) so that AppArmor can learn what the applications tendencies are and prompt you for what behavior needs to be taken in certain circumstances. The second is useful once you have an existing profile and need to allow/deny access to certain tasks which have already been logged during enforce or complain modes.

Lets start aa-genprof on our script:

user@ae:~$ aa-genprof example.sh
[ ...long message about aa-genprof...]
 
Profiling: example.sh 
 
[(S)can system log for AppArmor events] / (F)inish

Leave this prompt as is, now run the example.sh script in a new terminal window. Note that aa-genprof requires us to run the program while it is monitoring the process so that it can scan the log to learn about all the events the program creates. It will then propose rules to add to the profile for us. Once you have run the script, press the 's' key in the genprof terminal window:

[(S)can system log for AppArmor events] / (F)inish 
Reading log entries from /var/log/audit/audit.log. 
Updating AppArmor profiles in /etc/apparmor.d. 
 
Profile:  /home/user/bin/example.sh 
Execute:  /usr/bin/touch 
Severity: 3 
 
(I)nherit / (C)hild / (N)amed / (X) ix On / (D)eny / Abo(r)t / (F)inish

Let's stop for a second here and get a grasp of what exactly we are looking at. This is what a prompt from the AppArmor tools looks like, it is telling you that a profile (usually denoted by the absolute path of the program) is attempting to access or execute a certain file OR that the process requires access to a certain capability from the kernel. If you are not familiar with capabilities don't worry about them for now.

AppArmor also attempts to provide a severity warning based on what the process is trying to do (1 being low warning and 10 being very serious) but this is not always accurate as some programs legitimately need access to resources which count as a very severe warning. For example the Chrome(ium) browser requires access to CAP_SYS_ADMIN to create a secure sandbox for its child processes but AppArmor would give a severity 10 warning for this.

We should also note how AppArmor gives us several different options here on what we can do but let's focus on the core ones:

Inherit: Creates a rule that is denoted by "ix" within the profile, causes the executed binary to inherit permissions from the parent profile.
Child: Creates a rule that is denoted by "Cx" within the profile, requires a sub-profile to be created within the parent profile and rules must be separately generated for this child (prompts will appear when running scans on the parent).
Deny: Creates a rule that AppArmor prepends with "deny" at the start of the line within the profile, causes the parents access to the resource be denied.
Abort: Exits the AppArmor program without saving any changes.
Finish: Exits the AppArmor program but WILL save changes.

This is really the tricky part with generating your own AppArmor profiles, you need to know what permissions the need to be given and denied. Due to this I highly recommend using preexisting profiles if it is at all possible, especially if they are peer-reviewed and distributed by a trusted party. For this script however we are fine with just giving /usr/bin/touch Inherit permissions. After that a similar prompt will come up for /usr/bin/rm and since we know the script also legitimately uses that, we will give Inherit access once again.

The next prompt seems a bit different than these previous two:

Complain-mode changes: 
 
Profile:  /home/user/bin/example.sh 
Path:     /dev/tty 
Mode:     rw 
Severity: 9 
 
  1 - #include <abstractions/consoles>  
  2 - #include <abstractions/libvirt-qemu>  
  3 - #include <abstractions/ubuntu-konsole>  
  4 - #include <abstractions/ubuntu-xterm>  
 [5 - /dev/tty] 
[(A)llow] / (D)eny / (I)gnore / (G)lob / Glob with (E)xtension / (N)ew / Abo(r)t / (F)inish / (M)ore

Notice how there is a new field called "Mode" that tells us what permissions the script is requiring when accessing the "Path". Also note how there are some new options available, the core ones are:

Allow: Allow access to the path with the requested permissions
Deny: Deny access to the path with the requested permissions
Ignore: Skip this prompt, it will appear again the next time you run logprof

Since this script is prints to the console it needs access to the TTY interface and so it can be allowed. Another prompt follows for /etc/ld.so.preload which according to the man page for ld.so is used for "list of ELF shared objects to be loaded before the program". This can be allowed as it is harmless. The next prompt shows something interesting, see if you can recognize its importance:

Profile:  /home/user/bin/example.sh 
Path:     /home/user/bin/data/sample.txt 
Mode:     rw 
Severity: unknown 
 
 [1 - /home/user/bin/data/sample.txt] 
[(A)llow] / (D)eny / (I)gnore / (G)lob / Glob with (E)xtension / (N)ew / Abo(r)t / (F)inish / (M)ore

This should look familiar as this is the file that is created by the script! AppArmor is notifying us that example.sh tries to create a file sample.txt in the directory /home/user/bin/data. Once again we know this is legitimate behavior for the script, and so we can allow it. Finally, we get a prompt asking if we wish to save changes or not. Press 's' to save changes and then 'f' to finish.

= Changed Local Profiles = 
 
The following local profiles were changed. Would you like to save them? 
 
 [1 - /home/user/bin/example.sh] 
(S)ave Changes / Save Selec(t)ed Profile / [(V)iew Changes] / View Changes b/w (C)lean profiles / Abo(r)t 
Writing updated profile for /home/user/bin/example.sh. 
 
Profiling: /home/user/bin/example.sh 
 
[(S)can system log for AppArmor events] / (F)inish 
 
Reloaded AppArmor profiles in enforce mode. 
 
Please consider contributing your new profile! 
See the following wiki page for more information: 
http://wiki.apparmor.net/index.php/Profiles 
 
Finished generating profile for /home/user/bin/example.sh.

Confirm the script still works by running it again, AppArmor should not have interfered with the script.

Learning To Adapt #

Up to this point we have seen how to use AppArmor to profile and enforce rules against a process. However, this was all done under the assumption that the example.sh script will never change. Unfortunately software in the real world does not work this way, it is often updated which causes it to require addition or removal of access for certain files and features. This means we need to be able to leverage AppArmor, so it allows us to update profiles as programs change. This is where aa-logprof and aa-mergeprof come in.

aa-logprof #

This tool is used to scan the audit log for any events that AppArmor could not match to existing rules in a profile and will then prompt you for changes. Before we start using it, make sure that the example.sh profile is being enforced by AppArmor. You can check this using aa-status:

apparmor module is loaded. 
??? profiles are loaded. 
??? profiles are in enforce mode.
/home/user/bin/example.sh  <--- You should see it under this heading
...
??? profiles are in complain mode.
...
??? processes have profiles defined. 
??? processes are in enforce mode.
...
??? processes are in complain mode. 
??? processes are unconfined but have a profile defined.

Now open up the script and edit it so that instead of using the data directory, the script attempts to read and write in its own directory:

#!/bin/bash  
  
echo "This is an apparmor example."  
  
touch sample.txt  
echo "File created"  
  
rm sample.txt  
echo "File deleted"

Then just run the script and you should see an error message similar to this:

This is an apparmor example. 
touch: cannot touch 'sample.txt': Permission denied 
File created 
rm: cannot remove 'sample.txt': No such file or directory 
File deleted

Success! As strange as it may seem, this is good news because AppArmor has blocked the script from making changes to the system since it no longer matches the rules described in the profile. To fix this we need to have the AppArmor profile updated, so start aa-logprof and follow the prompts to allow access to the new paths and save changes:

user@ae:~$ aa-logprof 
Reading log entries from /var/log/audit/audit.log. 
Updating AppArmor profiles in /etc/apparmor.d. 
Enforce-mode changes: 
 
Profile:  /home/user/bin/example.sh 
Path:     /home/user/bin/sample.txt 
Mode:     w 
Severity: unknown 
 
 [1 - /home/user/bin/sample.txt] 
(A)llow / [(D)eny] / (I)gnore / (G)lob / Glob with (E)xtension / (N)ew / Abo(r)t / (F)inish / (M)ore 
Adding /home/user/bin/sample.txt w to profile
= Changed Local Profiles = 
 
The following local profiles were changed. Would you like to save them? 
 
 [1 - /home/user/bin/example.sh] 
(S)ave Changes / Save Selec(t)ed Profile / [(V)iew Changes] / View Changes b/w (C)lean profiles / Abo(r)t 
Writing updated profile for /home/user/bin/example.sh.

Now if the script is run, it completes successfully just like before:

user@ae:~$ ./example.sh  
This is an apparmor example. 
File created 
File deleted

And just like that have updated our scripts profile!

aa-mergeprof & AppArmor Profiles #

In this section I am not going to cover the technical details of aa-mergeprof as it is not a key tool with day to day AppArmor usage. Instead, I will provide a scenario and then explain what different things we see inside an AppArmor profile. It is more important to understand the profiles than it is being familiar with the less common tools.

Suppose we are in a situation where we have two systems A and B, along with two users Alice and Bob. When Alice updates the script on computer A, she makes the appropriate changes to the AppArmor profile. Bob at the same time makes different changes to the script and also updates the profile as appropriate. At some later date Alice and Bob combine their versions of the script together and now want to use AppArmor to enforce a policy on it. However, since they made changes to the profile separately they cannot just copy one of the profiles alone, they need to merge them together. This may seem like a very difficult task, especially for very large scripts but fortunately aa-mergeprof is able to save us from having to do most of the work!

Now lets take a look at the actual profiles. All AppArmor profiles will be stored in the /etc/apparmor.d directory. If the example.sh is stored in /home/user/bin/example.sh then you will find its respective profile in /etc/apparmor.d/home.user.bin.example.sh. Open that up in a text editor and let's see what it says:

# Last Modified: Wed Jul 27 23:19:01 2016 
#include <tunables/global> 
 
/home/user/bin/example.sh { 
  #include <abstractions/base> 
  #include <abstractions/bash> 
 
  /bin/bash ix, 
  /dev/tty rw, 
  /etc/ld.so.preload r, 
  /home/user/bin/data/sample.txt rw, 
  /home/user/bin/example.sh r, 
  /home/user/bin/sample.txt w, 
  /usr/bin/rm rix, 
  /usr/bin/touch rix, 
 
}

Below is what a profile declaration looks like, this tells AppArmor the path to the program and that anything within the {} is designated for this process.

/home/user/bin/example.sh {
    ...
}

Then the following lines are used to pull in generic rules from some preconfigured libraries:

#include <abstractions/base> 
#include <abstractions/bash>

After that there are a bunch of lines that define a file as well as the permissions the profile will allow them to access. Don't worry too much about what they do individually and instead focus on the fact that they are single lines to describe access to a single resource.

Let's reverse the changes we made before and force the script to require the data directory only once more. Recall that to deny permission to a resource AppArmor will prepend the line with deny. You will need to change the current profile so that it will deny access to the /home/user/bin/sample.txt file AND delete the line for /home/user/bin/data/sample.txt. Once done it should look like this:

# Last Modified: Wed Jul 27 23:19:01 2016 
#include <tunables/global> 
 
/home/user/bin/example.sh { 
  #include <abstractions/base> 
  #include <abstractions/bash> 
 
  /bin/bash ix, 
  /dev/tty rw, 
  /etc/ld.so.preload r, 
  /home/user/bin/example.sh r, 
  deny /home/user/bin/sample.txt w, 
  /usr/bin/rm rix, 
  /usr/bin/touch rix, 
 
}

One thing I should point out is that whenever you make manual changes to an AppArmor profile you need to tell AppArmor to do a refresh or else your changes will not take effect. This can be done either through a command (ideal) or just by restarting the AppArmor service (not ideal).

apparmor_parser -r /etc/apparmor.d/home.user.bin.example.sh

If you try to run the script now you should get the same error we had before:

This is an apparmor example. 
touch: cannot touch 'sample.txt': Permission denied 
File created 
rm: cannot remove 'sample.txt': No such file or directory 
File deleted

Awesome! This is proof that the changes made to our policies not only have a legitimate impact on the access control of the system, but they can be changed on the fly as needed. There are more delicate details that we can explore about profiles but for an introduction this much is sufficient.

Going To The Next Level #

Up to this point you have done enough with AppArmor that you can use it on a day-to-day basis to manage profiles on a single system. However, in large or constantly changing environments the tools used so far are not enough, we need to be able to scale our monitoring and management of profiles as well as learn how to differentiate good policies from bad policies. For now, I want to leave you with an interesting thought about AppArmor and we will try and address it in the part 2 of this guide.

An Interesting Idea #

Recall the description of AppArmor from the official wiki:

AppArmor is an mandatory access control (MAC) like security system for Linux. It is designed to work with standard Unix discretionary access control (DAC) permissions while being easy to use and deploy, by allowing an admin to confine only specific applications.

Recall that DAC can be used to restrict access to files and directories through a set of permissions defined by the owner of the file (and to some extent the system defaults). The question we can ask is that if AppArmor is capable of restricting access to files and directories is it enough to just use it to completely replace our DAC system? Consider the following:

Suppose Bob had created some confidential file that he did not want to share with Alice but placed it in a path that she had full access to. Now imagine that he realized this and decided to use only AppArmor to prevent her and any other user from accessing it. Could it be done? Can Bob guarantee that other users would never be able to have unauthorized access to the file?

Additional Notes #

complain mode status will still enforce any explicit deny rules in a profile ↩︎