MacOS Standard Library Hardening

[aarmaane]

What
Clang has support for a hardened version of the C++ standard library (i.e. debug version) and support was recently added to the latest version of Apple Clang. We should consider adding this to our tutorials.

Where
Address Sanitizers.
XCode tutorial maybe. It should already have this enabled by default, so it isn't necessary to have a section for it.

Why
We already enable the debug version of the standard library for GCC, so it's worth enabling this for Apple Clang users as well. If list iterator hardening is ever added (currently not implemented), it would save students a lot of headache during the list-editor project. Students often have issues with their usage of iterators and don't find out until they submit to the autograder (where the GCC debug library reports those issues).

References
Clang Hardening Modes Documentation
Apple Hardening Documentation

Possible Problems

• If you're not on the latest version of MacOS, are you able to install the latest version of Apple Clang?
• There's some overlap in functionality with the address sanitizers.

[awdeorio]

IIRC, the reason for -D_GLIBCXX_DEBUG is to catch out-of-bounds vector accesses. I think these are caught on macOS/Clang by ASAN.

#include <iostream>
#include <vector>
using namespace std;

int main() {
  cout << "hello from main!\n";
  vector<int> v = {0, 0};  // v contains 2 items
  cout << v[2] << "\n";    // off the end of v
}

Could you give a minimal example of list iterator code that you mentioned? I don't quite understand situation.

[jamesjuett]

This is somewhat related to #22 .

The GLIBCXX_DEBUG enables additional assertions in the libstdc++ standard library implementation, e.g. to catch indexing outside the bounds of a vectors proper elements (via a bounds checking assertion that is enabled), even in cases where you don't go outside the actual underlying block of memory allocated for the vector. This case would not be caught by ASAN since there is no invalid memory access if the underlying buffer happens to be large enough.

Previously, Apple Clang didn't ship with a debug version of libc++, so we didn't previously have a way for students to catch this.

Similarly, sanitizer tools would not necessarily catch running and iterator off the end of a linked list, since the underlying implementation might actually use a circularly linked list with a sentinel node. So this would be another case where the debug implementation is helpful to add additional assertions based on invalid operations from a container perspective as well as from a memory error perspective.

[aarmaane]

Example:

#include <iostream>
#include <list>
using namespace std;

int main() {
  list<int> l = {1, 2};  
  auto itr = --l.begin();  // invalid iterator
  cout << *itr << "\n";    // doesn't trigger address sanitizer
}

This doesn't get caught by address sanitizers. If you enable the GLIBCXX_DEBUG flag in GCC, you'll get a proper error:

/usr/include/c++/13/debug/safe_iterator.h:621:
In function:
    gnu_debug::_Safe_iterator<_Iterator, _Sequence, 
    std::bidirectional_iterator_tag>& gnu_debug::_Safe_iterator<_Iterator, 
    _Sequence, std::bidirectional_iterator_tag>::operator--() [with 
    _Iterator = std::_List_iterator<int>; _Sequence = std::debug::list<int>]

Error: attempt to decrement a dereferenceable (start-of-sequence) iterator.

[awdeorio]

Thanks for the added detail @aarmaane and @jjuett

I had forgotten the subtleties of GLIBCXX_DEBUG. It's nice to learn that macOS/Clang now supports the similar -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG. We should definitely start including this new flag in the tutorials.

TL;DR: Clang doesn't seem to detect the list example you suggested.

This is somewhat related to #22 .

Maybe we should update the flags we recommend and ship with, which are basically debug flags.

Drew's tests

I tried this out on macOS with Clang and GCC.

$ clang++ --version
Apple clang version 16.0.0 (clang-1600.0.26.6)
$ g++-14 --version
g++-14 (Homebrew GCC 14.2.0_1) 14.2.0

Out-of-bounds vector access

For an out-of-bounds vector access with the flags, I'm seeing non-zero exit as expected on both Clang and GCC. Without the flags, both display silent undefined behavior.

Here's the code, which is copied from the EECS 280 ASAN tutorial.

#include <iostream>
#include <vector>
using namespace std;

int main() {
  cout << "hello from main!\n";
  vector<int> v = {0, 0};  // v contains 2 items
  cout << v[2] << "\n";    // off the end of v
}

Clang exits with an error.

$ clang++ -std=c++17 -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG test.cpp
$ ./a.out
hello from main!
Abort trap: 6

GCC exits with an error.

$ g++-14 -std=c++17 -D_GLIBCXX_DEBUG test.cpp
$ ./a.out 
hello from main!
/opt/homebrew/Cellar/gcc/14.2.0_1/include/c++/14/debug/vector:508:
In function:
    std::debug::vector<_Tp, _Allocator>::reference std::debug::vector<_Tp, 
    _Allocator>::operator[](size_type) [with _Tp = int; _Allocator = 
    std::allocator<int>; reference = int&; size_type = long unsigned int]

Error: attempt to subscript container with out-of-bounds index 2, but 
container only holds 2 elements.

Objects involved in the operation:
    sequence "this" @ 0x16f71f2d0 {
      type = std::debug::vector<int, std::allocator<int> >;
    }
Abort trap: 6

Invalid list iterator reference

For an invalid list iterator, with the flags, I'm seeing GCC non-zero exit as expected, but Clang exits normally. Without the flags, both display silent undefined behavior, which happens to be wrapping around to the beginning.

Here's the code.

#include <iostream>
#include <list>
using namespace std;

int main() {
  list<int> l = {1, 2};  
  auto itr = --l.begin();  // invalid iterator
  cout << *itr << "\n";    // doesn't trigger address sanitizer
}

Here's Clang with an normal exit code. I was expecting an error and a non-zero exit code.

$ clang++ -std=c++17 -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG test.cpp
$ ./a.out
2
$ echo $?
0

And here's GCC with an expected error non-zero exit.

$ g++-14 -std=c++17 -D_GLIBCXX_DEBUG test.cpp
$ ./a.out
/opt/homebrew/Cellar/gcc/14.2.0_1/include/c++/14/debug/safe_iterator.h:713:
In function:
    gnu_debug::_Safe_iterator<_Iterator, _Sequence, 
    std::bidirectional_iterator_tag>& gnu_debug::_Safe_iterator<_Iterator, 
    _Sequence, std::bidirectional_iterator_tag>::operator--() [with 
    _Iterator = std::_List_iterator<int>; _Sequence = std::debug::list<int>]

Error: attempt to decrement a dereferenceable (start-of-sequence) iterator.

Objects involved in the operation:
    iterator "this" @ 0x16d5cf2f0 {
      type = std::_List_iterator<int> (mutable iterator);
      state = dereferenceable (start-of-sequence);
      references sequence with type 'std::debug::list<int, std::allocator<int> >' @ 0x16d5cf2b8
    }
Abort trap: 6

[aarmaane]

Looking into the Clang documentation more, unfortunately it looks like iterator support isn't a given. Most containers don't have hardened iterators implemented yet, including list. But more importantly, it's up to the vendor to enable iterator hardening when they build the standard library for their platform. It's unclear if Apple has enabled it.

The rest of the benefits still stand though, which would be beneficial.

[awdeorio]

I agree that it's a still a good idea to recommend -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG for Clang users

[jamesjuett]

It seems like there are a few options:

1. We could simply add -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG to the Mac options in our sanitizers tutorial.
2. We could take some step of recommending debug mode by default, i.e. adding to our distributed Makefiles with the projects. There might be a few places to double check that this doesn't break anything, e.g. that it doesn't impact efficiency too much on the images or classifier projects with large test cases.
3. Do 1. right now and create a separate issue for 2. (or resurrect Compile for Debug as Default #22) to potentially resolve later

This might also be a good time to double check instructions for debugging these sorts of assertion failures. The printed error doesn't have a line number, but you should be able to run them in a visual debugger and see where the assertion was triggered, potentially needing to move up a level or more on the call stack. (This is somewhat significant, since the sanitizers do generally give you a line number - enabling the debug option means that more errors will be caught with a failed assert rather than sanitizer.)

Maybe we should add something to the sanitizers tutorial that indicates how to do this (the current example shows sanitizer output). Or a link to the assertions guide https://eecs280staff.github.io/tutorials/assertions_guide.html#debug-failed-assertions?

[awdeorio]

I like Option 3. Simple and effective in the short term. Best solution for the long term.

Maybe we can then discuss the best place for debug flags in a separate issue, possibly inspired by #22.

Maybe we should add something to the sanitizers tutorial that indicates how to do this (the current example shows sanitizer output). Or a link to the assertions guide https://eecs280staff.github.io/tutorials/assertions_guide.html#debug-failed-assertions?

YES! Cross-referencing tutorials is perfect

[jamesjuett]

@awdeorio I think we can probably close this since #235 is merged. What do you think?

[awdeorio]

Agreed!