{"id":20292135,"url":"https://github.com/apsislabs/phi_attrs","last_synced_at":"2025-10-11T07:32:10.395Z","repository":{"id":39614553,"uuid":"133590619","full_name":"apsislabs/phi_attrs","owner":"apsislabs","description":"HIPAA compliant PHI access logging for Ruby on Rails.","archived":false,"fork":false,"pushed_at":"2025-02-13T21:01:48.000Z","size":228,"stargazers_count":28,"open_issues_count":17,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-11T11:56:18.685Z","etag":null,"topics":["gem","hipaa","phi","phi-log","rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apsislabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-05-16T00:59:33.000Z","updated_at":"2025-03-13T10:51:48.000Z","dependencies_parsed_at":"2025-04-11T11:33:37.859Z","dependency_job_id":"84c410e3-b555-4451-9660-534ac403f22b","html_url":"https://github.com/apsislabs/phi_attrs","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/apsislabs/phi_attrs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apsislabs%2Fphi_attrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apsislabs%2Fphi_attrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apsislabs%2Fphi_attrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apsislabs%2Fphi_attrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apsislabs","download_url":"https://codeload.github.com/apsislabs/phi_attrs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apsislabs%2Fphi_attrs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268519094,"owners_count":24263043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gem","hipaa","phi","phi-log","rails"],"created_at":"2024-11-14T15:15:45.721Z","updated_at":"2025-10-11T07:32:05.356Z","avatar_url":"https://github.com/apsislabs.png","language":"Ruby","readme":"# phi_attrs [![Gem Version](https://badge.fury.io/rb/phi_attrs.svg)](https://badge.fury.io/rb/phi_attrs) [![Spec CI](https://github.com/apsislabs/phi_attrs/workflows/Spec%20CI/badge.svg)](https://github.com/apsislabs/phi_attrs/actions)\n\n\nHIPAA compliant PHI access logging for Ruby on Rails.\n\nAccording to [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html) `§ 164.312(b)`, HIPAA covered entities are required to:\n\n\u003e Implement hardware, software, and/or procedural mechanisms that record and examine activity in information systems that contain or use electronic protected health information.\n\nThe `phi_attrs` gem is intended to assist with implementing logging to comply with the access log requirements of `§ 164.308(a)(1)(ii)(D)`:\n\n\u003e Information system activity review (Required). Implement procedures to regularly review records of information system activity, such as audit logs, access reports, and security incident tracking reports.\n\nTo do so, `phi_attrs` extends `ActiveRecord` models by adding automated logging and explicit access control methods. The access control mechanism creates a separate `phi_access_log`.\n\n**Please Note:** while `phi_attrs` helps facilitate access logging, it still requires due diligence by developers, both in ensuring that models and attributes which store PHI are flagged with `phi_model` and that calls to `allow_phi!` properly attribute both a _unique_ identifier and an explicit reason for PHI access.\n\n**Please Note:** there are other aspects of building a HIPAA secure application which are not addressed by `phi_attrs`, and as such _use of `phi_attrs` on its own does not ensure HIPAA Compliance_. For further reading on how to ensure your application meets the HIPAA security standards, review the [HHS Security Series Technical Safeguards](https://www.hhs.gov/sites/default/files/ocr/privacy/hipaa/administrative/securityrule/techsafeguards.pdf) and [Summary of the HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/laws-regulations/index.html), in addition to consulting your compliance and legal counsel.\n\n## Stability\n\nAll versions of this project below `1.0.0` should be considered unstable beta software. Even minor-version updates may introduce breaking changes to the public API at this stage. We strongly suggest that you lock the installed version in your Gemfile to avoid unintended breaking updates.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'phi_attrs'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install phi_attrs\n\n## Initialize\n\nCreate an initializer to configure the PHI log file location. Log rotation can be configured with log_shift_age and log_shift_size (disabled by default).\n\nExample:\n\n `config/initializers/phi_attrs.rb`\n\n```ruby\nPhiAttrs.configure do |conf|\n  conf.log_path = Rails.root.join(\"log\", \"phi_access_#{Rails.env}.log\")\n  conf.log_shift_age  = 10            # how many logs to keep of `log_shift_size` or frequency to rotate ('daily', 'weekly' or 'monthly'). Disable rotation with 0 (default).\n  conf.log_shift_size = 100.megabytes # size in bytes when using `log_shift_age` as a number\nend\n```\n\n## Usage\n\n```ruby\nclass PatientInfo \u003c ActiveRecord::Base\n  phi_model\n\n  exclude_from_phi :last_name\n  include_in_phi :birthday\n\n  def birthday\n    Time.current\n  end\nend\n```\n\nAccess is granted on a instance level:\n\n```ruby\ninfo = PatientInfo.new\ninfo.allow_phi!(\"allowed_user@example.com\", \"Customer Service\")\n```\n\n*When using on an instance if you find it in a second place you will need to call allow_phi! again.*\n\nor a class:\n\n```ruby\nPatientInfo.allow_phi!(\"allowed_user@example.com\", \"Customer Service\")\n```\n\nAs of version `0.1.5`, a block syntax is available. As above, this is available on both class and instance levels.\n\nNote the lack of a `!` at the end. These methods should not be used alongside the mutating (bang) methods! We recommend using the block syntax for tighter control.\n\n```ruby\npatient = PatientInfo.find(params[:id])\npatient.allow_phi('allowed_user@example.com', 'Display Customer Data') do\n  @data = patient.to_json\nend # Access no longer allowed beyond this point\n```\n\nor a block on a class:\n\n```ruby\nPatientInfo.allow_phi('allowed_user@example.com', 'Display Customer Data') do\n  @data = PatientInfo.find(params[:id]).to_json\nend # Access no longer allowed beyond this point\n```\n\n### Controlling What Is PHI\n\nWhen you include `phi_model` on your active record all fields except the id will be considered PHI.\n\nTo remove fields from PHI tracking use `exclude_from_phi`:\n\n```ruby\n# created_at and updated_at will be accessible as normal\nclass PatientInfo \u003c ActiveRecord::Base\n  phi_model\n\n  exclude_from_phi :created_at, :updated_at\nend\n```\n\nTo add a method as PHI use `include_in_phi`. Include takes precedence over exclude so a method that appears in both will be considered PHI.\n\n```ruby\n# birthday and node will throw PHIExceptions if accessed without permission\nclass PatientInfo \u003c ActiveRecord::Base\n  phi_model\n\n  include_in_phi :birthday, :note\n\n  def birthday\n    Time.current\n  end\n\n  attr_accessor :note\nend\n```\n\n#### Example Usage\n\nExample of `exclude_from_phi` and `include_in_phi` with inheritance.\n\n```ruby\nclass PatientInfo \u003c ActiveRecord::Base\n  phi_model\nend\n\npi = PatientInfo.new(first_name: \"Ash\", last_name: \"Ketchum\")\npi.created_at\n# PHIAccessException!\npi.last_name\n# PHIAccessException!\npi.allow_phi \"Ash\", \"Testing PHI Attrs\" { pi.last_name }\n# \"Ketchum\"\n```\n\n```ruby\nclass PatientInfoTwo \u003c PatientInfo\n  exclude_from_phi :created_at\nend\n\npi = PatientInfoTwo.new(first_name: \"Ash\", last_name: \"Ketchum\")\npi.created_at\n# current time\npi.last_name\n# PHIAccessException!\npi.allow_phi \"Ash\", \"Testing PHI Attrs\" { pi.last_name }\n# \"Ketchum\"\n```\n\n```ruby\nclass PatientInfoThree \u003c PatientInfoTwo\n  include_in_phi :created_at # Changed our mind\nend\n\npi = PatientInfoThree.new(first_name: \"Ash\", last_name: \"Ketchum\")\npi.created_at\n# PHIAccessException!\npi.last_name\n# PHIAccessException!\npi.allow_phi \"Ash\", \"Testing PHI Attrs\" { pi.last_name }\n# \"Ketchum\"\n```\n\n### Extending PHI Access\n\nSometimes you'll have a single mental model that is composed of several `ActiveRecord` models joined by association. In this case, instead of calling `allow_phi!` on all joined models, we expose a shorthand of extending PHI access to related models.\n\n```ruby\nclass PatientInfo \u003c ActiveRecord::Base\n  phi_model\nend\n\nclass Patient \u003c ActiveRecord::Base\n  has_one :patient_info\n\n  phi_model\n\n  extend_phi_access :patient_info\nend\n\npatient = Patient.new\npatient.allow_phi!('user@example.com', 'reason')\npatient.patient_info.first_name\n```\n\n**NOTE:** This is not intended to be used on all relationships! Only those where you intend to grant implicit access based on access to another model. In this use case, we assume that allowed access to `Patient` implies allowed access to `PatientInfo`, and therefore does not require an additional `allow_phi!` check. There are no guaranteed safeguards against circular `extend_phi_access` calls!\n\n### Check If PHI Access Is Allowed\n\nTo check if PHI is allowed for a particular instance of a class call `phi_allowed?`.\n\n```ruby\npatient = Patient.new\npatient.phi_allowed? # =\u003e false\n\npatient.allow_phi('user@example.com', 'reason') do\n  patient.phi_allowed? # =\u003e true\nend\n\npatient.phi_allowed? # =\u003e false\n\npatient.allow_phi!('user@example.com', 'reason')\npatient.phi_allowed? # =\u003e true\n```\n\nThis also works if access was granted at the class level:\n\n```ruby\npatient = Patient.new\npatient.phi_allowed? # =\u003e false\nPatient.allow_phi!('user@example.com', 'reason')\npatient.phi_allowed? # =\u003e true\n```\n\nThere is also a `phi_allowed?` check available to see at the class level.\n\n```ruby\nPatient.phi_allowed? # =\u003e false\nPatient.allow_phi!('user@example.com', 'reason')\nPatient.phi_allowed? # =\u003e true\n```\n\n**Note that any instance level access grants will not change class level access:**\n\n```ruby\npatient = Patient.new\n\npatient.phi_allowed? # =\u003e false\nPatient.phi_allowed? # =\u003e false\n\npatient.allow_phi!('user@example.com', 'reason')\n\npatient.phi_allowed? # =\u003e true\nPatient.phi_allowed? # =\u003e false\n```\n\n\n### Revoking PHI Access\n\nYou can remove access to PHI with `disallow_phi!`. Each `disallow_phi!` call removes all access granted by `allow_phi!` at that level (class or instance).\n\nAt a class level:\n\n```ruby\nPatient.disallow_phi!\n```\n\nOr at a instance level:\n\n```ruby\npatient.disallow_phi!\n```\n\n* *If access is granted at both class and instance level you will need to call `disallow_phi!` twice, once for the instance and once for the class.*\n\nThere is also a block syntax of `disallow_phi` for temporary suppression phi access to the class or instance level\n\n```ruby\npatient = PatientInfo.find(params[:id])\npatient.allow_phi!('allowed_user@example.com', 'Display Patient Data')\npatient.disallow_phi do\n  @data = patient.to_json # PHIAccessException\nend # Access is allowed again beyond this point\n```\n\nor a block level on a class:\n\n```ruby\nPatientInfo.allow_phi!('allowed_user@example.com', 'Display Patient Data')\nPatientInfo.disallow_phi do\n  @data = PatientInfo.find(params[:id]).to_json # PHIAccessException\nend # Access is allowed again beyond this point\n```\n\n* *Reminder instance level `phi_allow` will take precedent over a class level `disallow_phi`*\n\n### Manual PHI Access Logging\n\nIf you aren't using `phi_record` you can still use `phi_attrs` to manually log phi access in your application. Where ever you are granting PHI access call:\n\n```ruby\nuser = 'user@example.com'\nmessage = 'accessed list of all patients'\nPhiAttrs.log_phi_access(user, message)\n```\n\n### Reason Translations\n\nIt can get cumbersome to pass around PHI Access reasons. PHI Attrs allows you to\nuse your translations file to keep your code dry. If your translation file\ncontains a reason for the combination of controller, action, and model you can\nskip passing `reason`:\n\n```ruby\nmodule Admin\n  class PatientDashboardController \u003c ApplicationController\n    def expelliarmus\n      patient_info.allow_phi(current_user) do\n        # reason tries to use `phi.admin.patient_dashbaord.expelliarmus.patient_info`\n      end\n    end\n\n    def leviosa\n      patient_info.allow_phi(current_user) do\n        # reason tries to use `phi.admin.patient_dashbaord.leviosa.patient_info`\n      end\n    end\n  end\nend\n```\n\nThe following `en.yml` file would work:\n\n```yml\nen:\n  phi:\n    admin:\n      patient_dashboard:\n        expelliarmus:\n          patient_info: \"Patient Disarmed\"\n        leviosa:\n          patient_info: \"Patient Levitated\"\n```\n\nIf you have a typo in your en.yml file or you choose not to provide a translation\nfor your phi reasons your code will fail with an ArgumentError. To assist you in\ndebugging PHI Attrs will print a `:warn` message with the expected location for\nthe missing translation.\n\nIf you would like to change from `phi` to a custom location you can set the path in your initializer.\n\n```ruby\nPhiAttrs.configure do |conf|\n  conf.translation_prefix = 'custom_prefix'\nend\n```\n\n### Default User\n\nPassing around the current user can clutter your code. PHI Attrs allows you to\nconfigure a controller method that will be called to get the currently logged in\nuser:\n\n#### `config/initializers/phi_attrs.rb`\n\n```ruby\nPhiAttrs.configure do |conf|\n  conf.current_user_method = :user_email\nend\n```\n\n#### `app/controllers/home_controller.rb`\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  private\n\n  def user_email\n    current_user\u0026.email\n  end\nend\n```\n\nWith the above code, any call to `allow_phi` (that starts in a controller\nderived from ApplicationController) will use the result of `user_email` as the\nuser argument of `allow_phi`.\n\nNote that if you have a default user, but choose not to use translations for\nreasons you'll have to pass `nil` as the user:\n\n```ruby\nperson_phi.allow_phi(nil, \"Because I felt like looking at PHI\") do\n  # Allows PHI\nend\n```\n\n### Request UUID\n\nIt can be helpful to include the Rails request UUID to match up your general application\nlogs to your PHI access logs. The following snippet will prepend your PHI access logs\nwith the request UUID.\n\n#### `app/controllers/application_controller.rb`\n\n```ruby\naround_action :tag_phi_log_with_request_id\n\n...\n\nprivate\n\ndef tag_phi_log_with_request_id\n  PhiAttrs::Logger.logger.tagged(\"Request ID: #{request.uuid}\") do\n    yield\n  end\nend\n```\n## Best Practices\n\n* Mix and matching `instance`, `class` and `block` syntaxes for allowing/denying PHI is not recommended.\n  * Sticking with one style in your application will make it easier to understand what access is granted and where.\n\n## Development\n\nIt is recommended to use the provided `docker-compose` environment for development to help ensure dependency consistency and code isolation from other projects you may be working on.\n\n### Begin\n\n    $ docker-compose up\n    $ bin/ssh_to_container\n\n### Tests\n\nTests are written using [RSpec](https://rspec.info/) and are setup to use [Appraisal](https://github.com/thoughtbot/appraisal) to run tests over multiple rails versions.\n\n    $ bin/run_tests\n    or for individual tests:\n    $ bin/ssh_to_container\n    $ bundle exec appraisal rspec spec/path/to/spec.rb\n\nTo run just a particular rails version:\n    $  bundle exec appraisal rails_6.1 rspec\n    $  bundle exec appraisal rails_7.0 rspec\n\n### Console\n\nAn interactive prompt that will allow you to experiment with the gem.\n\n    $ bin/ssh_to_container\n    $ bin/console\n\n### Local Install\n\nRun `bin/setup` to install dependencies. Then, run `bundle exec appraisal rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n### Versioning\n\nTo release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/apsislabs/phi_attrs.\n\nAny PRs should be accompanied with documentation in `README.md`.\n\n### Releasing\n\n* Squash and merge your PR, including a bump to `lib/phi_attrs/version.rb`\n* Draft a new release, creating a new tag with the new version number from `version.rb`, i.e. `v0.3.2`\n* Auto-generate release notes, add any context if necessary\n* Publish release; release will be automatically built and published to rubygems\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Legal Disclaimer\n\nApsis Labs, LLP is not a law firm and does not provide legal advice. The information in this repo and software does not constitute legal advice, nor does usage of this software create an attorney-client relationship.\n\nApsis Labs, LLP is not a HIPAA covered entity, and usage of this software does not create a business associate relationship, nor does it enact a business associate agreement.\n\n[Full Disclaimer](./DISCLAIMER.txt)\n\n---\n\n# Built by Apsis\n\n[![apsis](https://s3-us-west-2.amazonaws.com/apsiscdn/apsis.png)](https://www.apsis.io)\n\n`phi_attrs` was built by Apsis Labs. We love sharing what we build! Check out our [other libraries on Github](https://github.com/apsislabs), and if you like our work you can [hire us](https://www.apsis.io) to build your vision.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapsislabs%2Fphi_attrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapsislabs%2Fphi_attrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapsislabs%2Fphi_attrs/lists"}